@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-drawio-studio/styles/schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Agents365-ai/drawio-skill/styles/schema.json",
+  "title": "drawio-skill preset",
+  "type": "object",
+  "required": ["name", "version", "palette", "roles", "shapes", "font", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema":    { "type": "string" },
+    "name":       { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "version":    { "type": "integer", "const": 1 },
+    "default":    { "type": "boolean" },
+    "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type":          { "type": "string", "enum": ["xml", "image", "built-in", "hand-authored"] },
+        "path":          { "type": "string" },
+        "extracted_at":  { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+      }
+    },
+    "palette": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"],
+      "properties": {
+        "primary":   { "$ref": "#/$defs/colorPair" },
+        "success":   { "$ref": "#/$defs/colorPair" },
+        "warning":   { "$ref": "#/$defs/colorPair" },
+        "accent":    { "$ref": "#/$defs/colorPair" },
+        "danger":    { "$ref": "#/$defs/colorPair" },
+        "neutral":   { "$ref": "#/$defs/colorPair" },
+        "secondary": { "$ref": "#/$defs/colorPair" }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "service":  { "$ref": "#/$defs/slotName" },
+        "database": { "$ref": "#/$defs/slotName" },
+        "queue":    { "$ref": "#/$defs/slotName" },
+        "gateway":  { "$ref": "#/$defs/slotName" },
+        "error":    { "$ref": "#/$defs/slotName" },
+        "external": { "$ref": "#/$defs/slotName" },
+        "security": { "$ref": "#/$defs/slotName" }
+      }
+    },
+    "shapes": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "properties": {
+        "service":   { "type": "string" },
+        "database":  { "type": "string" },
+        "queue":     { "type": "string" },
+        "decision":  { "type": "string" },
+        "external":  { "type": "string" },
+        "container": { "type": "string" }
+      }
+    },
+    "font": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fontFamily", "fontSize"],
+      "properties": {
+        "fontFamily":    { "type": "string" },
+        "fontSize":      { "type": "integer", "minimum": 8, "maximum": 36 },
+        "titleFontSize": { "type": "integer", "minimum": 8, "maximum": 48 },
+        "titleBold":     { "type": "boolean" }
+      }
+    },
+    "edges": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["style", "arrow"],
+      "properties": {
+        "style":      { "type": "string" },
+        "arrow":      { "type": "string" },
+        "dashedFor":  { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "extras": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sketch":            { "type": "boolean" },
+        "globalStrokeWidth": { "type": "number", "minimum": 0.5, "maximum": 6 }
+      }
+    }
+  },
+  "$defs": {
+    "colorPair": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fillColor", "strokeColor"],
+          "properties": {
+            "fillColor":   { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+            "strokeColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }
+          }
+        }
+      ]
+    },
+    "slotName": {
+      "type": "string",
+      "enum": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"]
+    }
+  }
+}

package/skills/fec-e2e-testing/SKILL.md

@@ -20,10 +20,12 @@ description: Use when creating, maintaining, debugging, or reviewing real-browse
 7. 对关键浏览器能力、支付、权限、上传和实时通信流程，记录测试环境、种子数据和清理策略。
 8. 测试数据必须可重复：优先使用 API seed、数据库 fixture、测试账号或 mock 服务；随机数据需带唯一前缀并在 teardown 清理。
 
-## Detailed References
+## 详细参考
 
-- Load [references/playwright-patterns.md](references/playwright-patterns.md) for directory layout, Page Object, spec structure, config, flaky debugging, and artifact examples.
-- Load [references/e2e-advanced.md](references/e2e-advanced.md) when the task needs CI examples, Markdown report templates, Web3/wallet flows, high-risk financial flows, or visual regression setup.
+- 需要目录结构、Page Object、spec 组织、配置、flaky 调试和产物示例时，加载 [references/playwright-patterns.md](references/playwright-patterns.md)。
+- 需要 CI 示例和 Markdown 报告模板时，加载 [references/e2e-ci-reporting.md](references/e2e-ci-reporting.md)。
+- 需要 Web3/钱包流程或高风险金融流程时，加载 [references/e2e-special-scenarios.md](references/e2e-special-scenarios.md)。
+- 需要跨页面截图或视觉回归配置时，加载 [references/e2e-visual-regression.md](references/e2e-visual-regression.md)。
 
 ## Constraints
 

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

@@ -0,0 +1,62 @@
+# E2E CI 与报告
+
+## CI 集成（示例）
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+        env:
+          CI: true
+          BASE_URL: ${{ vars.STAGING_URL }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+Cypress：固定 `CYPRESS_baseUrl` 或配置文件中的 `baseUrl`，失败截图/视频同样建议上传 artifact。
+
+## E2E 报告模板（Markdown）
+
+输出或归档测试报告时可采用下列结构，便于复盘：
+
+```markdown
+# E2E 测试报告
+
+**日期：** YYYY-MM-DD HH:mm
+**耗时：** X 分 Y 秒
+**结果：** 通过 / 失败
+
+## 摘要
+
+- 总计 X | 通过 Y | 失败 Z | 不稳定/跳过 说明
+
+## 失败用例
+
+### 用例名
+
+- **文件：** `tests/e2e/xxx.spec.ts:行号`
+- **错误：** 简述断言或超时信息
+- **截图/Trace：** 路径或 artifact 名称
+- **建议修复：** 可执行结论
+
+## 产物
+
+- HTML 报告：`playwright-report/index.html`
+- Trace / 视频 / 截图：CI artifact 或本地 `test-results/`
+```

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

@@ -0,0 +1,52 @@
+# E2E 特殊场景
+
+## Web3 / 钱包注入（Playwright）
+
+在 **`page.goto` 之前**通过 `context.addInitScript` 注入 mock，避免依赖真实插件：
+
+```typescript
+test("连接钱包", async ({ page, context }) => {
+  await context.addInitScript(() => {
+    (window as unknown as { ethereum?: unknown }).ethereum = {
+      isMetaMask: true,
+      request: async ({ method }: { method: string }) => {
+        if (method === "eth_requestAccounts")
+          return ["0x1234567890123456789012345678901234567890"];
+        if (method === "eth_chainId") return "0x1";
+        return null;
+      },
+    };
+  });
+
+  await page.goto("/");
+  await page.getByTestId("connect-wallet").click();
+  await expect(page.getByTestId("wallet-address")).toContainText("0x1234");
+});
+```
+
+链 ID、账户列表与业务契约保持一致即可。
+
+## 金融或高风险操作
+
+- **禁止**在真实生产环境执行真实资金操作；使用 **staging、mock 或 `test.skip`**。
+- 断言**预览金额、成功态**与**关键接口 200** 后再结束用例，超时给足（如链上确认场景）。
+
+```typescript
+test("下单预览与成功态", async ({ page }) => {
+  test.skip(process.env.NODE_ENV === "production", "生产环境跳过真实交易");
+
+  await page.goto("/markets/demo");
+  await page.getByTestId("position-yes").click();
+  await page.getByTestId("trade-amount").fill("1.0");
+
+  const preview = page.getByTestId("trade-preview");
+  await expect(preview).toContainText("1.0");
+
+  await page.getByTestId("confirm-trade").click();
+  await page.waitForResponse(
+    (resp) => resp.url().includes("/api/trade") && resp.status() === 200,
+    { timeout: 30_000 },
+  );
+  await expect(page.getByTestId("trade-success")).toBeVisible();
+});
+```

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

@@ -0,0 +1,60 @@
+# E2E 视觉回归测试
+
+通过截图快照对比检测非预期的 UI 变化。适用于 CSS 重构、设计 Token 更新、组件改版等场景。
+
+## 基础用法
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("首页布局与基线一致", async ({ page }) => {
+  await page.goto("/");
+  await page.waitForLoadState("networkidle");
+
+  // 全页截图对比 - 首次运行自动生成基线
+  await expect(page).toHaveScreenshot("homepage-full.png", {
+    fullPage: true,
+    maxDiffPixels: 100, // 允许的轻微像素差异（抗锯齿等）
+  });
+});
+
+test("按钮组件视觉一致", async ({ page }) => {
+  await page.goto("/components/buttons");
+  const submitButton = page.getByTestId("submit-button");
+  await expect(submitButton).toHaveScreenshot("submit-button.png");
+});
+```
+
+## 屏蔽动态内容
+
+时间、随机 ID、第三方广告等动态元素会导致误报，使用 `mask` 屏蔽：
+
+```typescript
+await expect(page).toHaveScreenshot("dashboard.png", {
+  mask: [
+    page.locator(".live-clock"),
+    page.locator(".random-id"),
+    page.locator(".ad-banner"),
+  ],
+});
+```
+
+## 禁用动画
+
+CSS 动画会导致截图不一致，注入样式禁用动画后再截图：
+
+```typescript
+await page.addStyleTag({
+  content:
+    "*, *::before, *::after { animation-duration: 0s !important; transition-duration: 0s !important; }",
+});
+await expect(page).toHaveScreenshot("animated-page.png");
+```
+
+## 基线管理
+
+- **首次运行**: `npx playwright test` 失败但自动生成基线到 `tests/` 目录
+- **更新基线**: UI 有意变更时 `npx playwright test --update-snapshots`
+- **CI 一致性**: 基线必须在与 CI 相同的 OS（Linux/Ubuntu）上生成，字体渲染在 macOS 与 Linux 间存在差异
+- **多浏览器**: 每个 project 独立生成基线（Chromium/Firefox/WebKit 渲染结果不同）
+- **基线文件**: 纳入 `.gitignore` 或 Git LFS 管理，避免仓库膨胀

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

@@ -11,13 +11,13 @@ description: Use when building or reviewing substantial forms with React Hook Fo
 
 ## Procedure
 
-1. 先判断复杂度：10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时使用 React Hook Form + Zod；极简表单可用原生受控组件。
-2. 用 Zod 定义运行时 schema，并用 `z.infer` 推导 TypeScript 类型；schema 是外部输入边界，不要只写 TS 类型。
-3. `useForm` 必须提供 `defaultValues`，通过 `zodResolver` 统一校验；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
-4. 第三方受控组件用 `Controller`，原生 input 优先 `register`；不要混用两套状态源。
+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；大型表单用局部订阅和子组件隔离控制重渲染。
 
-## Quick Start
+## React Quick Start
 
 ```tsx
 import { zodResolver } from "@hookform/resolvers/zod";
@@ -59,17 +59,17 @@ export function LoginFormView() {
 }
 ```
 
-## Detailed References
+## 详细参考
 
-涉及 `Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
+涉及是否需要表单库、框架选型、`Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
 
 ## Constraints
 
-- React Hook Form 默认非受控；只有第三方受控组件才用 `Controller`。
-- `defaultValues` 必须完整，避免 undefined 触发受控/非受控警告。
-- `reset()` 应传服务器返回或明确的完整默认对象。
+- 沿用仓库既有表单库、schema 库和组件库适配方式，不为单个表单引入第二套体系。
+- 默认值必须完整，避免 undefined 触发受控/非受控警告或初始化抖动。
+- reset 应传服务器返回或明确的完整默认对象。
 - 异步校验必须 debounce 或放到提交边界，避免每次键入请求。
-- Zod `refine` / `superRefine` 的 `path` 必须指向实际字段。
+- schema 级联动校验的错误 path 必须指向实际字段。
 
 ## Expected Output
 

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

@@ -1,6 +1,35 @@
 # 高级表单模式
 
-## Controller
+## 先判断是否需要表单库
+
+- 1-3 个字段、无复杂校验、无动态字段、无组件库适配压力的表单，可用框架原生状态、浏览器约束校验和轻量提交状态。
+- 需要动态字段、跨字段校验、多步流程、文件上传、异步校验、服务端错误回填或明显输入卡顿时，再引入专门表单方案。
+- 表单库只管理字段状态和校验流程，不替代 API 错误映射、权限判断、可访问性标注或服务端最终校验。
+
+## 选型参考
+
+先沿用项目已有表单库、schema 库和组件库适配方式；新增依赖时再按场景选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| 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 Hook Form Controller
 
 ```tsx
 <Controller
@@ -18,7 +47,7 @@
 
 用于不暴露原生 `ref` 的 Select、DatePicker、RichEditor 等组件。
 
-## 动态字段
+## React Hook Form 动态字段
 
 ```tsx
 const { fields, append, remove } = useFieldArray({
@@ -36,7 +65,7 @@ const { fields, append, remove } = useFieldArray({
 
 `key` 必须使用 `field.id`，不要使用数组 index。
 
-## 联动校验
+## Zod 联动校验
 
 ```ts
 const schema = z
@@ -50,7 +79,7 @@ const schema = z
   });
 ```
 
-## 文件上传
+## Zod 文件上传校验
 
 ```ts
 const schema = z.object({
@@ -67,6 +96,6 @@ const schema = z.object({
 ## 性能
 
 - 用 `useWatch` 或字段级订阅替代全表单 watch。
-- 大表单拆成 memoized 子组件。
+- 大表单拆成 memoized 子组件或框架等价的局部更新单元。
 - 高频输入不要每次键入触发网络校验。
 - 多步表单要明确每步 schema 和跨步最终 schema。

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

@@ -0,0 +1,56 @@
+---
+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 自检, 自动修复.
+---
+
+# 图片生成与图表工作流
+
+## Purpose
+
+生成或编辑图表、视觉资产和图片工作流，并对导出的 PNG 做可复查的自检与修复迭代。
+
+## Procedure
+
+1. 判断产物类型
+   - 文本、结构和连线准确性优先时，用 Mermaid、SVG、HTML/CSS、canvas 或图表库生成可编辑源，再导出 PNG。
+   - 审美、质感、照片、插画、漫画、产品图或品牌氛围优先时，用图片生成或编辑工具，再把最终资产保存到项目或报告目录。
+
+2. 明确输入与约束
+   - 收集受众、用途、尺寸、语言、必须出现的文本、品牌限制、可编辑源格式、导出格式和禁用元素。
+   - 对海报、UI 样机、品牌板和产品图，先写出一行视觉读取：目标用户、场景、可信感来源、主视觉锚点。
+
+3. 选择生成路线
+   - ER 图、UML 类图、序列图、技术架构图、ML/深度学习、流程图等，优先按 [diagram-workflows.md](references/diagram-workflows.md) 建立结构化源。
+   - 海报、UI 样机、产品图、信息图、学术图、漫画、头像、分镜、品牌板和图像编辑，按 [artifact-routing.md](references/artifact-routing.md) 选择生成、编辑或混合路线。
+
+4. 导出并自检 PNG
+   - 每次交付前都读取导出的 PNG，检查主体是否真实渲染、文字是否截断、连线是否堆叠、节点是否重叠。
+   - 有布局 manifest 时运行：
+     ```bash
+     node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --manifest layout.json --format markdown
+     ```
+   - 没有 manifest 时仍运行 PNG 基础检查：
+     ```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 或重导出。
+
+6. 交付记录
+   - 说明最终源文件、PNG 路径、生成路线、QA 轮次、发现并修复的问题、仍需人工确认的文字或品牌风险。
+
+## Constraints
+
+- 文本密集图不要只靠位图模型生成；必须保留可编辑结构化源。
+- 不把截图、假数据或占位图当成最终产品图，除非用户明确要求概念稿。
+- 不直接覆盖原图；编辑工作流默认输出新文件。
+- 不为追求美观牺牲可读标签、连线归属、图例、坐标轴和可访问替代说明。
+- PNG helper 只做检测和建议；修复必须回到源、prompt 或布局参数。
+- 自检结果不能替代人工确认专有名词、公式、论文图注、品牌规范和合规信息。
+
+## Expected Output
+
+产出可编辑源、最终 PNG 或编辑后图片，并附带生成路线与 QA 结果。图表应结构清晰、标签不截断、连线不混乱；视觉资产应匹配用途、尺寸、品牌语气和交付路径。

package/skills/fec-image-generation/references/artifact-routing.md

@@ -0,0 +1,80 @@
+# Artifact Routing
+
+## Mode selection
+
+Choose the execution mode before writing a prompt:
+
+| Mode | Use when | Behavior |
+| ---- | -------- | -------- |
+| Deterministic source | Text, labels, charts, connectors, or exact geometry must be correct | Build Mermaid, SVG, HTML/CSS, canvas, plotting, or design-tool source first, then export PNG. |
+| Host-native image tool | The task needs raster aesthetics, illustration, product mood, photo-like output, or image editing and the current environment has an image tool | Write a structured prompt and call the host image tool. Save or report the prompt when future edits are likely. |
+| Prompt-only advisor | No image tool is available or the user only wants a prompt | Produce the final prompt, usage notes, and verification checklist. Do not imply an image was generated. |
+| Hybrid | Exact text or UI structure plus generated imagery are both needed | Generate supporting imagery, then compose final text/layout in SVG, HTML, canvas, or a design tool. |
+
+Do not introduce local image API scripts, provider-specific environment variables, or OpenAI-compatible gateway assumptions as part of this workflow. If a project already owns such a pipeline, treat it as a host tool and keep prompts provider-neutral.
+
+## Route by output
+
+| Output | Preferred route | Notes |
+| ------ | --------------- | ----- |
+| Poster / ad creative | Image generation, then optional layout polish in HTML/SVG or design tool | Lock exact copy before generation; recompose text outside the bitmap when accuracy matters. |
+| UI mockup | HTML/CSS or design-tool mockup first; raster generation only for mood or hero references | Keep controls readable and avoid fake product states in final handoff. |
+| Product image | Image generation or edit with reference constraints | Preserve brand, perspective, material, and lighting; do not overwrite original assets. |
+| Infographic | Structured SVG/HTML/canvas for text and charts; generated illustrations only as supporting media | Export PNG after layout QA. |
+| Academic figure | Deterministic plotting, SVG, Mermaid, LaTeX, or canvas | Accuracy beats style; keep source reproducible. |
+| Comic / storyboard | Image generation with panel manifest | Track panel count, exact captions, characters, scene continuity, and reading order. |
+| Avatar | Image generation or edit | Ask only when identity, style, or usage rights are ambiguous. |
+| Brand board | Mixed route: generated imagery, palette/type/layout board in HTML/SVG | Record palette roles, typography mood, imagery rules, and avoid-list. |
+| Image edit | Edit target plus explicit invariants | Preserve requested identity, composition, text, object, lighting, or background constraints. |
+
+## Visual asset categories
+
+Use these categories to pick prompt detail and verification focus:
+
+- Product and commerce: product image, packaging, lifestyle scene, marketplace board.
+- UI and interface: app mockup, chat scene, dashboard view, landing hero, social post.
+- Technical and academic: architecture, sequence, state, ER, method figure, graphical abstract.
+- Narrative and brand: poster, campaign key visual, storyboard, comic, avatar, mascot, brand board.
+- Information design: infographic, map, comparison, step-by-step guide, KPI board.
+- Editing: background replacement, object removal, local replacement, retouching, portrait edit.
+
+If the category is text-heavy or diagram-heavy, prefer a deterministic source or hybrid route.
+
+## Prompt contract
+
+Use this compact structure when calling an image tool:
+
+```text
+Asset type:
+Use:
+Canvas / aspect ratio:
+Audience:
+Required text:
+Subject:
+Composition:
+Style / brand tone:
+Reference assets:
+Must preserve:
+Avoid:
+Output:
+```
+
+For exact text, prefer adding text in SVG/HTML/design source after image generation. If text must be inside generated imagery, keep it short and verify manually.
+
+For image edits, add:
+
+```text
+Source image:
+Edit region:
+Invariants:
+Replacement:
+Lighting / perspective:
+```
+
+## Handoff checklist
+
+- Final image path is inside the workspace when the asset is project-bound.
+- Source or prompt is saved when future edits are likely.
+- Exact text, diagram labels, chart values, citations, and brand marks are manually checked.
+- Generated variants that were rejected are not referenced by code or docs.
+- If no image was generated, the final answer clearly states prompt-only mode.

package/skills/fec-image-generation/references/diagram-workflows.md

@@ -0,0 +1,43 @@
+# Diagram Workflows
+
+## Source selection
+
+| Diagram type | Preferred source | QA focus |
+| ------------ | ---------------- | -------- |
+| ER diagram | Mermaid ER, DBML, Graphviz, SVG | Cardinality labels, table names, key fields, crossing relations. |
+| UML class | Mermaid class, PlantUML, Graphviz | Inheritance direction, method/property wrapping, package grouping. |
+| Sequence | Mermaid sequence, PlantUML | Lifeline order, activation spans, async/return arrows, message text. |
+| Technical architecture | Mermaid flowchart, C4/Structurizr, SVG/HTML | Layer grouping, trust boundaries, data flow direction, legends. |
+| ML / deep learning | SVG/HTML/canvas | Tensor shapes, layer order, branch joins, repeated blocks, annotations. |
+| Flowchart | Mermaid flowchart, SVG | Decision labels, terminal states, loop-back readability, connector spacing. |
+
+## Minimum source manifest
+
+When the rendering path allows it, save a layout manifest next to the PNG:
+
+```json
+{
+  "canvas": { "width": 1280, "height": 720 },
+  "boxes": [
+    { "id": "api", "x": 80, "y": 120, "width": 220, "height": 96, "label": "API Gateway" }
+  ],
+  "connectors": [
+    { "id": "api-db", "from": "api", "to": "db", "points": [[300, 168], [560, 168]] }
+  ]
+}
+```
+
+Coordinates are PNG pixel coordinates after export. Boxes should cover visible label/node bounds, not just the center point.
+
+## Diagram repair playbook
+
+- **Overlapping nodes:** increase rank/column spacing, split clusters, or move low-priority annotations into a legend.
+- **Truncated labels:** widen the node, add manual line breaks, reduce label length, or increase export scale.
+- **Connector through labels:** add waypoints, route orthogonally around boxes, or move labels above the segment.
+- **Connector stacking:** separate parallel edges with different waypoints or bundle them with a shared labeled bus.
+- **Edge clipping:** increase outer padding or export viewBox/canvas size.
+- **Unreadable dense graph:** split into overview plus detail diagrams instead of shrinking everything.
+
+## Export guidance
+
+Prefer exporting at 2x scale for raster PNGs, then downsample only if text remains crisp. Keep the editable source committed or attached wherever future diagram changes are expected.

package/skills/fec-image-generation/references/png-qa-autofix.md

@@ -0,0 +1,30 @@
+# PNG QA And Autofix
+
+## Loop
+
+1. Export PNG from the editable source or image workflow.
+2. Inspect the PNG visually.
+3. Run `png-qa.mjs` with a manifest when available.
+4. Convert each issue into source, prompt, or layout changes.
+5. Repeat for 2 rounds by default, up to 5 when the user asks for more repair attempts.
+
+## Issue mapping
+
+| Issue | Repair |
+| ----- | ------ |
+| `blank-image` | Check export target, renderer errors, hidden layers, transparent fill, or failed image generation. |
+| `edge-clipping` | Add canvas padding, expand SVG viewBox, reduce subject scale, or export a larger frame. |
+| `box-overlap` | Increase spacing, reflow to grid/layers, split clusters, or shorten labels. |
+| `box-out-of-bounds` | Move the node inside canvas or increase canvas dimensions. |
+| `label-overflow` | Wrap text, widen the box, reduce copy, or increase font/container size together. |
+| `connector-through-label` | Add waypoints around boxes, move labels, or use orthogonal routing. |
+| `connector-stacking` | Offset parallel connectors or replace repeated lines with a labeled grouped path. |
+| `manifest-canvas-mismatch` | Regenerate the manifest from final export dimensions. |
+
+## Manifest quality
+
+The helper can only reason about overlaps and connectors when the manifest coordinates match the exported PNG. If the manifest is stale, repair the manifest first, then rerun QA.
+
+## Reporting
+
+Report the number of QA rounds and the final issue list. If issues remain because the source renderer cannot expose layout coordinates, say which checks were image-only and which require manual visual review.