lake-cimg 1.0.0 → 1.0.2

package/README.md

@@ -10,7 +10,6 @@
 - 处理过程输出体积对比；失败时非零退出码
 - **`picture` 子命令**：从单张 PNG/JPEG/WebP 源图一次生成 **AVIF + WebP + JPEG**，配合前端 `<picture>` 做渐进增强（不支持 GIF 动图源）
 - **`scan-code` 子命令**：扫描源码中的图片引用并结合真实像素尺寸给出 CLS / 比例等建议（只读）
-- **Agent Skill**：通过 [`npx skills add`](https://www.npmjs.com/package/skills) 安装 [`skills/cimg-audit`](skills/cimg-audit/SKILL.md)（技能名 **`cimg-audit`**，好记），在 Cursor 等环境里用自然语言驱动 `npx lake-cimg@latest …`
 
 ## 环境要求
 
@@ -156,38 +155,6 @@ npx lake-cimg@latest scan-code [path] [--no-recursive] [--limit <n>] [--issues-o
 
 适合在构建脚本或 Node 服务中复用同一套逻辑。
 
-## Agent Skill（Skills CLI / `npx skills add`）
-
-本仓库按 [Skills CLI](https://www.npmjs.com/package/skills) 约定提供可安装 Skill，见目录 [`skills/`](skills/README.md)（与 [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) 的 `skills/<name>/SKILL.md` 布局一致）。技能目录名为 **`cimg-audit`**（短、与包名一致，便于 `-s cimg-audit`）。
-
-**何时需要 / 触发条件（选用本 Skill 的典型场景）**
-
-- 对话或任务涉及：**图片体积与格式**（WebP/AVIF）、**`<picture>` / `srcset`**、**LCP / CLS / layout shift**、首屏大图
-- 要先做**只读**引用审计再改代码：用 **`npx lake-cimg@latest scan-code`** 出 JSON，再按需改标签或压缩
-- 希望 Agent **按固定流程**：先 `scan-code` → 再按需 `npx lake-cimg@latest` 压缩或 `picture` 多格式输出
-
-更细的英文说明见 [`skills/README.md` 的「When to use」一节](skills/README.md#when-to-use)。
-
-**从 GitHub 安装**（需已推送；将 `lake0090/lake-cimg` 换成你的 fork 若不同）：
-
-```bash
-# 安装到用户级（-g），仅本 skill（-s），跳过确认（-y）
-npx skills add lake0090/lake-cimg -s cimg-audit -g -y
-
-# 仅安装到当前项目
-npx skills add lake0090/lake-cimg -s cimg-audit -y
-```
-
-**本地克隆开发时**（在仓库根目录执行）：
-
-```bash
-npx skills add . -s cimg-audit -y
-```
-
-可选：`--agent cursor` 等，见 `npx skills add --help`。Skill 正文在 [`skills/cimg-audit/SKILL.md`](skills/cimg-audit/SKILL.md)，指导用 **`npx lake-cimg@latest scan-code`** 与压缩 / `picture` 子命令配合使用。
-
-安装 Skill 后，在 Agent 对话里可直接让模型按 Skill 流程执行（例如：先 `scan-code` 再按需压缩）；CLI 与 `npx` 均在本地执行，图片不会上传到云端。
-
 ## 常见问题
 
 - **写权限**：`-o` 指向的目录需可创建/写入；否则 sharp 或 `fs` 会报错。
@@ -198,7 +165,7 @@ npx skills add . -s cimg-audit -y
 
 - **Lighthouse 审计**：后续接入 [Lighthouse](https://developer.chrome.com/docs/lighthouse)（或 CI 中的 Lighthouse CI），对典型页面做性能 / 最佳实践等审计。
 - **审计前后对比**：在引入 `scan-code`、压缩、`picture` 等优化前后各跑一轮，保存报告（JSON/HTML），对比 LCP、CLS、资源体积等指标，量化改动效果。
-- **专项优化**：根据 Lighthouse 报告中的具体项（如 LCP 候选、未使用 CSS、图片尺寸等）做针对性迭代，与现有 CLI / Skill 工作流互补。
+- **专项优化**：根据 Lighthouse 报告中的具体项（如 LCP 候选、未使用 CSS、图片尺寸等）做针对性迭代，与现有 CLI 工作流互补。
 
 ## 发布到 npm（维护者）
 

package/bin/cimg.js

@@ -217,6 +217,20 @@ program
     }
   });
 
+function collectString(val, memo) {
+  const arr = memo ?? [];
+  arr.push(val);
+  return arr;
+}
+
+function parseAliasPair(val) {
+  const i = val.indexOf("=");
+  if (i <= 0) {
+    throw new Error("格式须为 key=相对路径，例如 @=src 或 @assets=src/assets");
+  }
+  return [val.slice(0, i).trim(), val.slice(i + 1).trim()];
+}
+
 program
   .command("scan-code [path]")
   .description(
@@ -231,17 +245,46 @@ program
     500
   )
   .option("--issues-only", "仅输出含 issues 的条目")
+  .option(
+    "--project-root <dir>",
+    "解析 /images/...、@/... 时的工程根目录（默认当前工作目录）"
+  )
+  .option(
+    "--public-dir <dir>",
+    "根路径下静态目录，可重复；用于解析以 / 开头的 URL 路径（默认 public、static）",
+    collectString
+  )
+  .option(
+    "--alias <pair>",
+    "路径别名 key=相对工程根的路径，可重复；默认 @=src。例: --alias @aaa=packages/aaa",
+    (v, prev) => {
+      const pair = parseAliasPair(v);
+      return [...(prev ?? []), pair];
+    },
+    []
+  )
   .action(async (pathArg, opts) => {
     const raw =
       pathArg != null && typeof pathArg === "string" ? pathArg.trim() : "";
     const root = resolveUserPath(raw !== "" ? raw : ".");
     const limit = Number.isNaN(opts.limit) ? 500 : opts.limit;
+    const aliasList = opts.alias ?? [];
+    const aliases =
+      aliasList.length > 0 ? Object.fromEntries(aliasList) : undefined;
+    const publicDirs = opts.publicDir;
     try {
       const result = await scanCodeReferences(root, {
         recursive: opts.recursive !== false,
         cwd: process.cwd(),
         limit,
         issuesOnly: !!opts.issuesOnly,
+        ...(opts.projectRoot != null && String(opts.projectRoot).trim() !== ""
+          ? { projectRoot: String(opts.projectRoot).trim() }
+          : {}),
+        ...(aliases != null ? { aliases } : {}),
+        ...(publicDirs != null && publicDirs.length > 0
+          ? { publicDirs }
+          : {}),
       });
       console.log(JSON.stringify(result, null, 2));
       process.exit(0);

package/lib/compress.js

@@ -9,9 +9,13 @@ import sharp from "sharp";
 import {
   SUPPORTED_EXT,
   DEFAULT_QUALITY,
-  DEFAULT_EFFORT,
   supportedFormatsLabel,
 } from "./constants.js";
+import {
+  applyResizeInside,
+  encodeWebpBuffer,
+  encodeJpegBuffer,
+} from "./sharpHelpers.js";
 
 /** Max concurrent tasks for processing images */
 const MAX_CONCURRENCY = Math.max(1, cpus().length);
@@ -59,23 +63,6 @@ function isSupported(filePath) {
   return SUPPORTED_EXT.includes(extname(filePath).toLowerCase());
 }
 
-/**
- * Encode pipeline to WebP buffer with shared sharp options.
- * @param {import("sharp").Sharp} pipeline
- * @param {number} quality
- * @param {{ lossless?: boolean }} [options]
- */
-async function encodeWebpBuffer(pipeline, quality, { lossless = false } = {}) {
-  return pipeline
-    .webp({
-      quality,
-      effort: DEFAULT_EFFORT,
-      smartSubsample: true,
-      lossless,
-    })
-    .toBuffer();
-}
-
 /**
  * Recursively collect image paths under dir (or return [dir] if dir is a file).
  * @param {string} inputPath - Absolute path to file or directory
@@ -135,15 +122,7 @@ export async function processOne(inputPath, options = {}) {
   let pipeline = sharp(inputBuffer, { animated: true });
   const inputMeta = await pipeline.metadata();
 
-  if (size != null && size > 0) {
-    pipeline = pipeline.resize({
-      width: size,
-      height: size,
-      fit: "inside",
-      withoutEnlargement: true,
-      background: { r: 0, g: 0, b: 0, alpha: 0 },
-    });
-  }
+  pipeline = applyResizeInside(pipeline, size);
 
   const outputBuffer = toWebp
     ? await encodeWebpBuffer(pipeline, quality, { lossless: false })
@@ -172,7 +151,7 @@ async function toFormatBuffer(pipeline, ext, quality) {
   switch (ext) {
     case ".jpg":
     case ".jpeg":
-      return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+      return encodeJpegBuffer(pipeline, quality);
     case ".png":
       return pipeline.png({ compressionLevel: 9 }).toBuffer();
     case ".webp":

package/lib/pictureStack.js

@@ -5,10 +5,13 @@
 import { readFile, writeFile, mkdir, stat } from "fs/promises";
 import { dirname, join, resolve, basename, extname } from "path";
 import sharp from "sharp";
-import { DEFAULT_QUALITY, DEFAULT_EFFORT } from "./constants.js";
-
-/** AVIF effort 0–9 (higher = slower, often smaller) */
-const DEFAULT_AVIF_EFFORT = 4;
+import { DEFAULT_QUALITY } from "./constants.js";
+import {
+  applyResizeInside,
+  encodeAvifBuffer,
+  encodeWebpBuffer,
+  encodeJpegBuffer,
+} from "./sharpHelpers.js";
 
 /**
  * @param {import("sharp").Sharp} pipeline - Configured pipeline (e.g. after resize)
@@ -16,22 +19,9 @@ const DEFAULT_AVIF_EFFORT = 4;
  */
 async function encodeTriple(pipeline, q) {
   const [avifBuf, webpBuf, jpegBuf] = await Promise.all([
-    pipeline
-      .clone()
-      .avif({ quality: q.avifQuality, effort: DEFAULT_AVIF_EFFORT })
-      .toBuffer(),
-    pipeline
-      .clone()
-      .webp({
-        quality: q.quality,
-        effort: DEFAULT_EFFORT,
-        smartSubsample: true,
-      })
-      .toBuffer(),
-    pipeline
-      .clone()
-      .jpeg({ quality: q.jpegQuality, mozjpeg: true })
-      .toBuffer(),
+    encodeAvifBuffer(pipeline.clone(), q.avifQuality),
+    encodeWebpBuffer(pipeline.clone(), q.quality),
+    encodeJpegBuffer(pipeline.clone(), q.jpegQuality),
   ]);
   return { avifBuf, webpBuf, jpegBuf };
 }
@@ -85,16 +75,10 @@ export async function processPictureStack(inputPath, options) {
   const inputBuffer = await readFile(absoluteIn);
   const sizeBefore = inputBuffer.length;
 
-  let pipeline = sharp(inputBuffer, { animated: false });
-  if (size != null && size > 0) {
-    pipeline = pipeline.resize({
-      width: size,
-      height: size,
-      fit: "inside",
-      withoutEnlargement: true,
-      background: { r: 0, g: 0, b: 0, alpha: 0 },
-    });
-  }
+  let pipeline = applyResizeInside(
+    sharp(inputBuffer, { animated: false }),
+    size
+  );
 
   const { avifBuf, webpBuf, jpegBuf } = await encodeTriple(pipeline, {
     quality,

package/lib/scanCodeReferences.js

@@ -40,6 +40,40 @@ const DEFAULT_EXCLUDE_DIRS = new Set([
 /** Relative ratio difference threshold (1% = 0.01) */
 const DEFAULT_RATIO_TOLERANCE = 0.01;
 
+/** Try these folders under projectRoot for URL paths like `/images/a.png` (public 静态资源) */
+const DEFAULT_PUBLIC_DIRS = ["public", "static"];
+
+/**
+ * @param {string} ref
+ * @param {Record<string, string>} aliases
+ * @returns {object | null}
+ */
+function matchAliasRef(ref, aliases) {
+  const keys = Object.keys(aliases)
+    .filter((k) => k !== "~")
+    .sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    const prefix = `${key}/`;
+    if (ref.startsWith(prefix)) {
+      return { key, rest: ref.slice(prefix.length) };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} abs
+ * @returns {Promise<boolean>}
+ */
+async function isExistingFile(abs) {
+  try {
+    const s = await stat(abs);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {string} text
  * @param {number} index
@@ -313,11 +347,17 @@ function extractPugImgRefs(content) {
 
 /**
  * @param {string} ref
- * @param {string} hostDir
- * @returns {{ status: 'ok', path: string } | { status: 'skip', reason: string }}
+ * @param {string} hostDir - 源码文件所在目录（相对路径 ./ ../ 以此为基准）
+ * @param {{
+ *   projectRoot: string,
+ *   aliases: Record<string, string>,
+ *   publicDirs: string[],
+ * }} opts
+ * @returns {Promise<{ status: 'ok', path: string } | { status: 'skip', reason: string }>}
  */
-function resolveLocalImageRef(ref, hostDir) {
-  const trimmed = ref.trim();
+async function resolveLocalImageRef(ref, hostDir, opts) {
+  const { projectRoot, aliases, publicDirs } = opts;
+  let trimmed = ref.trim();
   if (!trimmed) return { status: "skip", reason: "empty" };
   if (/^https?:\/\//i.test(trimmed)) {
     return { status: "skip", reason: "remote_url" };
@@ -325,14 +365,57 @@ function resolveLocalImageRef(ref, hostDir) {
   if (trimmed.startsWith("data:")) {
     return { status: "skip", reason: "data_uri" };
   }
-  if (trimmed.startsWith("@/") || trimmed.startsWith("~/") || trimmed.startsWith("~@/")) {
-    return { status: "skip", reason: "alias_path" };
+
+  if (trimmed.startsWith("~@/")) {
+    trimmed = `@/${trimmed.slice(3)}`;
   }
+
+  if (trimmed.startsWith("/") && !trimmed.startsWith("//")) {
+    const relFromWebRoot = trimmed.replace(/^\/+/, "");
+    for (const pd of publicDirs) {
+      const candidate = resolve(projectRoot, pd, relFromWebRoot);
+      if (await isExistingFile(candidate)) {
+        return { status: "ok", path: candidate };
+      }
+    }
+    return { status: "skip", reason: "public_path_not_found" };
+  }
+
+  if (trimmed.startsWith("~/")) {
+    const tildeBase = aliases["~"];
+    if (tildeBase == null || tildeBase === "") {
+      return { status: "skip", reason: "alias_path" };
+    }
+    const rest = trimmed.slice(2);
+    const candidate = resolve(projectRoot, tildeBase, rest);
+    if (await isExistingFile(candidate)) {
+      return { status: "ok", path: candidate };
+    }
+    return { status: "skip", reason: "alias_target_not_found" };
+  }
+
+  const aliasHit = matchAliasRef(trimmed, aliases);
+  if (aliasHit) {
+    const baseRel = aliases[aliasHit.key];
+    if (baseRel == null || baseRel === "") {
+      return { status: "skip", reason: "unknown_alias" };
+    }
+    const candidate = resolve(projectRoot, baseRel, aliasHit.rest);
+    if (await isExistingFile(candidate)) {
+      return { status: "ok", path: candidate };
+    }
+    return { status: "skip", reason: "alias_target_not_found" };
+  }
+
+  if (trimmed.startsWith("@") && trimmed.includes("/")) {
+    return { status: "skip", reason: "unknown_alias" };
+  }
+
   if (!IMG_EXT_RE.test(trimmed)) {
     return { status: "skip", reason: "not_image_extension" };
   }
-  const path = resolve(hostDir, trimmed);
-  return { status: "ok", path };
+  const pathAbs = resolve(hostDir, trimmed);
+  return { status: "ok", path: pathAbs };
 }
 
 /**
@@ -515,6 +598,9 @@ async function runPool(tasks, concurrency) {
  *   issuesOnly?: boolean,
  *   ratioTolerance?: number,
  *   metadataConcurrency?: number,
+ *   projectRoot?: string,
+ *   aliases?: Record<string, string>,
+ *   publicDirs?: string[],
  * }} [options]
  */
 export async function scanCodeReferences(rootDir, options = {}) {
@@ -525,8 +611,22 @@ export async function scanCodeReferences(rootDir, options = {}) {
     issuesOnly = false,
     ratioTolerance = DEFAULT_RATIO_TOLERANCE,
     metadataConcurrency = 8,
+    projectRoot: projectRootOpt,
+    aliases: aliasesOpt,
+    publicDirs: publicDirsOpt,
   } = options;
 
+  const projectRoot = resolve(cwd, projectRootOpt != null ? projectRootOpt : ".");
+  const aliases = {
+    "@": "src",
+    ...(aliasesOpt && typeof aliasesOpt === "object" ? aliasesOpt : {}),
+  };
+  const publicDirs =
+    Array.isArray(publicDirsOpt) && publicDirsOpt.length > 0
+      ? publicDirsOpt
+      : DEFAULT_PUBLIC_DIRS;
+  const resolveOpts = { projectRoot, aliases, publicDirs };
+
   const sourceExts =
     options.sourceExts != null
       ? new Set(
@@ -602,7 +702,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
   for (const { absHost, ref } of staged) {
     if (ref.parse?.dynamic || ref.parse?.missingSrc) continue;
     if (!ref.rawRef) continue;
-    const res = resolveLocalImageRef(ref.rawRef, absHost);
+    const res = await resolveLocalImageRef(ref.rawRef, absHost, resolveOpts);
     if (res.status === "ok") uniquePaths.add(res.path);
   }
 
@@ -691,7 +791,7 @@ export async function scanCodeReferences(rootDir, options = {}) {
       continue;
     }
 
-    const resolved = resolveLocalImageRef(r.rawRef, absHost);
+    const resolved = await resolveLocalImageRef(r.rawRef, absHost, resolveOpts);
     if (resolved.status === "skip") {
       const row = {
         file,

package/lib/sharpHelpers.js

@@ -0,0 +1,67 @@
+/**
+ * Shared Sharp pipeline helpers (resize + encode) for compress and picture stack.
+ */
+import { DEFAULT_EFFORT } from "./constants.js";
+
+const RESIZE_BACKGROUND = { r: 0, g: 0, b: 0, alpha: 0 };
+
+/** AVIF effort 0–9 (higher = slower, often smaller) */
+export const DEFAULT_AVIF_EFFORT = 4;
+
+/**
+ * Apply "fit inside" square resize when size > 0; otherwise return pipeline unchanged.
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number | null | undefined} size
+ * @returns {import("sharp").Sharp}
+ */
+export function applyResizeInside(pipeline, size) {
+  if (size == null || size <= 0) return pipeline;
+  return pipeline.resize({
+    width: size,
+    height: size,
+    fit: "inside",
+    withoutEnlargement: true,
+    background: RESIZE_BACKGROUND,
+  });
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ * @param {{ lossless?: boolean }} [options]
+ */
+export async function encodeWebpBuffer(
+  pipeline,
+  quality,
+  { lossless = false } = {}
+) {
+  return pipeline
+    .webp({
+      quality,
+      effort: DEFAULT_EFFORT,
+      smartSubsample: true,
+      lossless,
+    })
+    .toBuffer();
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ */
+export async function encodeJpegBuffer(pipeline, quality) {
+  return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+}
+
+/**
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ * @param {number} [effort]
+ */
+export async function encodeAvifBuffer(
+  pipeline,
+  quality,
+  effort = DEFAULT_AVIF_EFFORT
+) {
+  return pipeline.avif({ quality, effort }).toBuffer();
+}

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "lake-cimg",
-  "version": "1.0.0",
-  "description": "Batch image compression to WebP — CLI plus Agent Skills for frontend image audit (scan-code, picture stack)",
+  "version": "1.0.2",
+  "description": "Batch image compression to WebP — CLI with picture stack and scan-code for frontend image audit",
   "keywords": [
     "image",
     "compress",
     "webp",
     "sharp",
-    "agent-skills",
-    "skills",
-    "cursor"
+    "cli"
   ],
   "repository": {
     "type": "git",
@@ -23,8 +21,7 @@
   "files": [
     "bin",
     "lib",
-    "README.md",
-    "skills"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/skills/README.md

@@ -1,40 +0,0 @@
-# Skills (Skills CLI)
-
-This directory follows the layout expected by **[Skills CLI](https://www.npmjs.com/package/skills)** (`npx skills add`), same idea as [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills): each subfolder is one skill with a `SKILL.md`.
-
-| Skill | Summary |
-| --- | --- |
-| [cimg-audit](./cimg-audit/SKILL.md) | Audit `<img>` / Pug `img()` / imports / `url()` for CLS, aspect ratio, and format hints via `npx lake-cimg@latest scan-code` |
-
-### When to use
-
-Skill id **`cimg-audit`** — use it when the conversation or task touches:
-
-- **Performance / layout:** CLS, layout shift, LCP, hero images, `fetchPriority`
-- **Markup / assets:** `<img>` dimensions, `aspect-ratio`, `<picture>`, `srcset` / `sizes`, WebP / AVIF
-- **Workflow:** run **`scan-code`** first (read-only JSON), then fix markup and/or compress with **`npx lake-cimg@latest`** / **`picture`**
-
-The skill name `cimg-audit` is short for discovery; the YAML `description` in `SKILL.md` is what agents match against.
-
-Install from GitHub (after push):
-
-```bash
-npx skills add lake0090/lake-cimg -s cimg-audit -g -y
-```
-
-Install only this repo’s skill into the **current project** (run from another repo):
-
-```bash
-npx skills add lake0090/lake-cimg -s cimg-audit -y
-```
-
-Develop locally from a clone of this repository:
-
-```bash
-cd /path/to/lake-cimg
-npx skills add . -s cimg-audit -y
-```
-
-Use `-g` for a user-level install (`~/.cursor/skills/` etc., depending on agent). See `npx skills add --help` for `--agent` (e.g. `cursor`).
-
-Browse the registry at [skills.sh](https://skills.sh/).

package/skills/cimg-audit/SKILL.md

@@ -1,63 +0,0 @@
----
-name: cimg-audit
-description: >-
-  Audits HTML, Vue, Pug, JS, TS, TSX, and JSX image references against intrinsic
-  dimensions for CLS risk, aspect-ratio mismatches, and modern-format hints.
-  Use when optimizing images, fixing layout shift, LCP heroes, picture/srcset,
-  or running lake-cimg scan-code via npx lake-cimg@latest.
----
-
-# cimg image audit
-
-Run **`npx lake-cimg@latest`** from the **project root** (no global install).
-
-<a id="invoke-scan-code"></a>
-
-## Invoke `scan-code`
-
-Use **one** command starting with `npx` — **not** `cd … && npx …` (PowerShell 5.1 on Windows does not support `&&`).
-
-| `path` | Behavior |
-| --- | --- |
-| *(omitted)* | Scans **`.`** (current working directory). Run from repo root to cover the tree. |
-| **Directory** | Recursively scans supported sources under that folder (honors `--no-recursive`). |
-| **Single file** | Only that file. Extension must be `.html`, `.htm`, `.vue`, `.pug`, `.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, or `.jsx`. |
-
-**Output:** stdout is **only** pretty-printed JSON: `items[]` with `issues`, `hints`, `snippet`, `intrinsicWidth` / `intrinsicHeight` when metadata was read, plus top-level `summary` and scan metadata. **`--issues-only`** drops rows with empty `issues`. For **`missing_dimensions`**, use **`intrinsicWidth` / `intrinsicHeight`** on the same item and/or the English hint that repeats them.
-
-**Examples:**
-
-```bash
-npx lake-cimg@latest scan-code
-npx lake-cimg@latest scan-code /absolute/path/to/src
-npx lake-cimg@latest scan-code /absolute/path/to/about.pug
-```
-
-More flags: `npx lake-cimg@latest scan-code --help` (e.g. `--limit`, `--issues-only`, `--no-recursive`). Prefer an **absolute** `path` if the shell cwd may not be the repo root.
-
-## Workflow
-
-- [ ] **1. Scan (read-only):** `npx lake-cimg@latest scan-code [path]` — see **Invoke `scan-code`** above.
-- [ ] **2. Triage:** Prefer **`hints`** for what to change; use **`issues`** codes to group or filter. Common codes: `missing_dimensions`, `aspect_ratio_mismatch`, `suggest_modern_format` (consider AVIF/WebP + `<picture>` — match product/browser support), `needs_manual_review`, `missing_src`, `cannot_resolve`, `cannot_read_metadata`.
-- [ ] **3. Fix then optimize:** Apply markup fixes using [reference.md](reference.md) templates (`<img>`, `<picture>`). For **all** raster refs that need format or responsive delivery, not only one hero row. Then run compression / stacks: `npx lake-cimg@latest <path> [options]`; for AVIF + WebP + JPEG from one source: `npx lake-cimg@latest picture <input> -O <outDir>` (details: package [README.md](../../README.md)).
-
-## Rules of thumb
-
-- **Aspect ratio:** Match display ratio to intrinsic (w÷h), or use **`object-fit`** + explicit box / `aspect-ratio` for crop/letterbox.
-- **CLS:** Add `width` and `height` to `<img>`, or use CSS `aspect-ratio`. For `missing_dimensions`, fill in the exact `intrinsicWidth` / `intrinsicHeight`.
-- **Responsive:** `<picture>` and/or **`srcset` + `sizes`**; each `<source type="…">` must match the real file type; Generate width variants with `picture … -s <px>` or separate exports.
-- **LCP:** At most one hero per view: **`fetchPriority="high"`**, **`loading="eager"`**; lazy-load the rest.
-- **Alt:** Describe content and purpose; no keyword stuffing; **`alt=""`** only for decorative images.
-
-## What the scanner cannot resolve
-
-Dynamic **`src`** without a static path → **`needs_manual_review`**. **`http(s):`**, **`data:`**, and path aliases (**`@/`**, **`~/`**, etc.) → **`cannot_resolve`** (no alias map reads; no network fetch).
-
-If **`hints`** mention alias skip: use **`rawRef`** and map the alias via Vite/webpack/tsconfig/Nuxt config. With a **real filesystem path**, run `npx lake-cimg@latest scan <resolved-path>` on assets or re-run **`scan-code`** on markup that uses resolvable relative paths. If unresolved, triage without intrinsic dimensions.
-
-## Other CLI (after scan-code)
-
-| Command | Role |
-| --- | --- |
-| `npx lake-cimg@latest <path>` | Compress / WebP — see `npx lake-cimg@latest --help` (`-o`, `-s`, `-q`, `-r`). |
-| `npx lake-cimg@latest picture <input> -O <outDir>` | One raster → AVIF + WebP + JPEG for `<picture>`. |

package/skills/cimg-audit/reference.md

@@ -1,49 +0,0 @@
-# Image markup templates
-
-Supplement for [SKILL.md](SKILL.md). Copy-paste starting points; adjust paths, dimensions, and `sizes` to match your assets and layout.
-
-## Basic `<img>`
-
-**When:** Single raster URL; reserve space for CLS. **Check:** `width` / `height` match intrinsic pixels (or use `aspect-ratio` for fluid); meaningful `alt` or `alt=""` if decorative.
-
-```html
-<img
-  src="photo.jpg"
-  width="1200"
-  height="800"
-  alt="Describe subject and purpose on this page"
-  loading="lazy"
-  decoding="async">
-```
-
-## `<picture>` + `srcset` + `sizes`
-
-**When:** AVIF/WebP stack with JPEG (or similar) fallback; responsive widths. **Check:** Each `<source type="…">` matches the real file type; `sizes` matches breakpoints; `<img>` is the final fallback with matching `srcset` / `sizes`.
-
-```html
-<picture>
-  <source
-    type="image/avif"
-    srcset="hero-400.avif 400w,
-            hero-800.avif 800w,
-            hero-1200.avif 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw">
-  <source
-    type="image/webp"
-    srcset="hero-400.webp 400w,
-            hero-800.webp 800w,
-            hero-1200.webp 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw">
-  <img
-    src="hero-800.jpg"
-    srcset="hero-400.jpg 400w,
-            hero-800.jpg 800w,
-            hero-1200.jpg 1200w"
-    sizes="(max-width: 600px) 100vw, 50vw"
-    width="1200"
-    height="600"
-    alt="Describe subject and purpose on this page"
-    loading="lazy"
-    decoding="async">
-</picture>
-```