ima2-gen 2.0.15 → 2.0.16

package/README.md

@@ -97,6 +97,36 @@ Ctrl+C now performs a clean shutdown — closing the database, stopping child pr
 - **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
 - **Observable jobs**: active and recent jobs are tracked with safe logs and request IDs.
 
+### Agent Skills
+
+ima2-gen ships three packaged skills for AI coding agents. These are Markdown
+instruction files that agents load to get structured workflows for image/video
+generation, frontend asset production, and design direction discovery.
+
+| Skill | Command | What It Covers |
+|-------|---------|----------------|
+| **Core** | `ima2 skill` | CLI reference, prompting protocol, provider routing, Korean text, video workflows |
+| **Frontend** | `ima2 skill front` | Asset pipeline (parallel gen, variant selection, provider routing), motion/video for web, responsive, a11y, anti-slop, 30+ reference files |
+| **UI/UX Design** | `ima2 skill uiux` | Image-first design direction discovery, UX states, design-isms, product personalities, DESIGN.md workflow, 18 reference files |
+
+```bash
+ima2 skill ls            # list available skills
+ima2 skill front         # print the frontend skill
+ima2 skill uiux          # print the design skill
+ima2 skill front path    # print file path (for agents)
+ima2 skill front --json  # JSON wrapper (for agents)
+ima2 skill front refs    # list reference modules (35 files)
+ima2 skill front ref motion        # load one reference module
+ima2 skill install --dir <path>     # install skills to agent's skill dir
+ima2 skill install --tmp            # install to temp dir (fallback)
+```
+
+The Frontend and UI/UX skills are production-grade design engineering guides
+adapted for the ima2 workflow. They cover typography, color systems, layout
+discipline, Korean UX patterns, motion choreography, and visual verification,
+with every asset generation step mapped to `ima2 gen`, `ima2 video`, and
+`ima2 multimode` commands.
+
 ### SSE Multiplexing
 
 The web UI uses a single `GET /api/events` Server-Sent Events connection for all generation progress. Multimode, node, and video requests are submitted as async POST (`202 { requestId }`) and progress events are multiplexed through a shared event bus. This eliminates the browser 6-connection limit that previously caused gallery hangs during concurrent generation. CLI clients that do not send `async: true` still receive per-request SSE streams for backward compatibility.

package/bin/commands/skill.js

@@ -1,24 +1,80 @@
-import { existsSync, readFileSync } from "fs";
-import { dirname, join, relative } from "path";
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, cpSync } from "fs";
+import { dirname, join, relative, basename, extname, resolve } from "path";
+import { tmpdir } from "os";
 import { fileURLToPath } from "url";
 import { parseArgs } from "../lib/args.js";
 import { die, json, out } from "../lib/output.js";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const SKILL_PATH = join(ROOT, "skills", "ima2", "SKILL.md");
+const SKILLS_DIR = join(ROOT, "skills");
 const PACKAGE_PATH = join(ROOT, "package.json");
+const KNOWN_SKILLS = {
+    ima2: {
+        dir: "ima2",
+        description: "Core CLI reference, prompting protocol, provider routing",
+    },
+    front: {
+        dir: "ima2-front",
+        description: "Frontend implementation: assets, motion, responsive, a11y, anti-slop",
+    },
+    uiux: {
+        dir: "ima2-uiux",
+        description: "Design direction discovery, UX judgment, image-first ism workflow",
+    },
+};
 const HELP = `
-  ima2 skill [path] [--json]
+  ima2 skill [<name>] [path|refs|ref <name>|install] [--json]
 
-  Print the packaged ima2 Markdown skill for agents.
+  Print packaged ima2 Markdown skills and reference modules for agents.
+  Each skill ships a SKILL.md + a references/ directory. Reference modules
+  are loaded by agents via relative paths from the SKILL.md.
 
   Commands:
-    ima2 skill          Print skills/ima2/SKILL.md
-    ima2 skill path     Print resolved skill path
-    ima2 skill --json   Print a JSON wrapper around the Markdown skill
+    ima2 skill              Print skills/ima2/SKILL.md (core)
+    ima2 skill front        Print skills/ima2-front/SKILL.md (frontend)
+    ima2 skill uiux         Print skills/ima2-uiux/SKILL.md (design)
+    ima2 skill ls            List all available skills
+    ima2 skill <name> path   Print skill file path
+
+  Install to agent skill directory:
+    ima2 skill install --dir <path>          Copy all skills to <path>/
+    ima2 skill install front --dir <path>    Copy only the frontend skill
+    ima2 skill install uiux --dir <path>     Copy only the design skill
+    ima2 skill install --tmp                 Copy to $TMPDIR/ima2-skills/ (ephemeral)
+    ima2 skill install front --tmp           Copy one skill to temp dir
+
+    Each skill is a directory (e.g. <path>/ima2-front/) with SKILL.md +
+    references/. The agent determines its own skill path and passes --dir.
+    Use --tmp when no persistent path is available.
+
+  Reference modules (ad-hoc, without install):
+    ima2 skill <name> refs          List reference modules for a skill
+    ima2 skill <name> ref <name>    Print one reference module
+
+  Examples:
+    ima2 skill install --dir ~/.codex/skills        Install all skills
+    ima2 skill install front --dir ~/.codex/skills   Install frontend only
+    ima2 skill install --tmp                         Install to temp dir
+    ima2 skill front refs                            List frontend references
+    ima2 skill front ref motion                      Print references/motion.md
+    ima2 skill uiux ref design-isms                  Print references/design-isms.md
+
+  Agent integration:
+    The agent is responsible for resolving its own skill directory path.
+    Pass that path to --dir. After install, the agent reads SKILL.md and
+    follows references/ paths natively — no stdout piping needed.
+
+  Options:
+    --json         Print JSON wrapper
+    --dir <path>   Target directory for install
+    --tmp          Use $TMPDIR/ima2-skills/ as target
+    -h, --help     Show help
 `;
 const FLAGS = {
     json: { type: "boolean" },
     help: { short: "h", type: "boolean" },
+    "with-refs": { type: "boolean" },
+    dir: { type: "string" },
+    tmp: { type: "boolean" },
 };
 function readPackageVersion() {
     try {
@@ -29,30 +85,293 @@ function readPackageVersion() {
         return "?";
     }
 }
-function readSkill() {
-    if (!existsSync(SKILL_PATH)) {
-        die(5, `packaged skill not found: ${SKILL_PATH}`);
+function resolveSkillPath(name) {
+    const entry = KNOWN_SKILLS[name];
+    if (!entry)
+        die(2, `unknown skill: "${name}". Available: ${Object.keys(KNOWN_SKILLS).join(", ")}`);
+    return join(SKILLS_DIR, entry.dir, "SKILL.md");
+}
+function readSkill(path) {
+    if (!existsSync(path)) {
+        die(5, `packaged skill not found: ${path}`);
+    }
+    return readFileSync(path, "utf-8");
+}
+function discoverRefs(skillDir) {
+    const refsDir = join(skillDir, "references");
+    if (!existsSync(refsDir))
+        return [];
+    const entries = [];
+    function walk(dir, prefix) {
+        for (const item of readdirSync(dir)) {
+            const full = join(dir, item);
+            const st = statSync(full);
+            if (st.isDirectory()) {
+                walk(full, prefix ? `${prefix}/${item}` : item);
+            }
+            else if (extname(item) === ".md") {
+                const nameNoExt = basename(item, ".md");
+                const qualName = prefix ? `${prefix}/${nameNoExt}` : nameNoExt;
+                const relFile = prefix ? `${prefix}/${item}` : item;
+                entries.push({
+                    name: qualName,
+                    file: relFile,
+                    relPath: `references/${relFile}`,
+                    absPath: full,
+                    lines: readFileSync(full, "utf-8").split("\n").length,
+                });
+            }
+        }
     }
-    return readFileSync(SKILL_PATH, "utf-8");
+    walk(refsDir, "");
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+function resolveRef(skillDir, refName) {
+    const refs = discoverRefs(skillDir);
+    const exact = refs.find((r) => r.name === refName);
+    if (exact)
+        return exact;
+    const byBase = refs.filter((r) => {
+        const parts = r.name.split("/");
+        return parts[parts.length - 1] === refName;
+    });
+    if (byBase.length === 1)
+        return byBase[0];
+    const partial = refs.filter((r) => r.name.includes(refName));
+    if (partial.length === 1)
+        return partial[0];
+    return null;
+}
+// ── Install helpers ──
+function copySkillDir(srcDir, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    cpSync(srcDir, destDir, { recursive: true });
+    // Count files copied
+    let count = 0;
+    function countFiles(dir) {
+        for (const item of readdirSync(dir)) {
+            const full = join(dir, item);
+            if (statSync(full).isDirectory())
+                countFiles(full);
+            else
+                count++;
+        }
+    }
+    countFiles(destDir);
+    return { files: count };
+}
+function resolveInstallDir(args) {
+    if (args.dir)
+        return resolve(String(args.dir));
+    if (args.tmp)
+        return join(tmpdir(), "ima2-skills");
+    return null;
 }
+function installSkills(targetBase, only, asJson) {
+    const results = [];
+    for (const [name, info] of Object.entries(KNOWN_SKILLS)) {
+        if (only && !only.includes(name))
+            continue;
+        const srcDir = join(SKILLS_DIR, info.dir);
+        if (!existsSync(join(srcDir, "SKILL.md")))
+            continue;
+        const destDir = join(targetBase, info.dir);
+        const { files } = copySkillDir(srcDir, destDir);
+        results.push({ name, dir: info.dir, dest: destDir, files });
+    }
+    if (results.length === 0 && only) {
+        die(2, `unknown skill: "${only.join(", ")}". Available: ${Object.keys(KNOWN_SKILLS).join(", ")}`);
+    }
+    if (asJson) {
+        json({
+            installed: results.map((r) => ({
+                name: r.name,
+                dir: r.dir,
+                path: r.dest,
+                files: r.files,
+            })),
+            target: targetBase,
+        });
+    }
+    else {
+        out(`\n  Installed ${results.length} ima2 skill${results.length === 1 ? "" : "s"} to ${targetBase}\n`);
+        for (const r of results) {
+            out(`    ✓  ${r.dir.padEnd(12)} ${r.files} files → ${r.dest}`);
+        }
+        out(`\n  Agents can now read SKILL.md + references/ via filesystem paths.\n`);
+    }
+}
+// ── Main command ──
 export default async function skillCmd(argv) {
     const args = parseArgs(argv, { flags: FLAGS });
     if (args.help) {
         out(HELP);
         return;
     }
-    if (args.positional[0] === "path") {
-        out(SKILL_PATH);
+    const positional = args.positional;
+    // ima2 skill install — copy skills to filesystem
+    if (positional[0] === "install") {
+        const targetBase = resolveInstallDir(args);
+        if (!targetBase) {
+            die(2, "specify --dir <path> or --tmp. The agent determines its own skill directory path.\n\n  Examples:\n    ima2 skill install --dir ~/.codex/skills\n    ima2 skill install front --dir ./skills\n    ima2 skill install --tmp");
+        }
+        // Collect optional skill names after "install"
+        const installNames = positional.slice(1).filter((p) => KNOWN_SKILLS[p]);
+        installSkills(targetBase, installNames.length > 0 ? installNames : null, !!args.json);
+        return;
+    }
+    // ima2 skill ls — list available skills
+    if (positional[0] === "ls" || positional[0] === "list") {
+        if (args.json) {
+            const skills = Object.entries(KNOWN_SKILLS).map(([name, info]) => {
+                const skillPath = join(SKILLS_DIR, info.dir, "SKILL.md");
+                return {
+                    name,
+                    dir: info.dir,
+                    description: info.description,
+                    path: relative(ROOT, skillPath),
+                    installed: existsSync(skillPath),
+                };
+            });
+            json({ skills });
+        }
+        else {
+            out("\n  Available ima2 skills:\n");
+            for (const [name, info] of Object.entries(KNOWN_SKILLS)) {
+                const skillPath = join(SKILLS_DIR, info.dir, "SKILL.md");
+                const status = existsSync(skillPath) ? "✓" : "✗";
+                out(`    ${status}  ${name.padEnd(8)} ${info.description}`);
+            }
+            out(`\n  Usage: ima2 skill <name>         Print a skill`);
+            out(`         ima2 skill <name> path     Print its file path`);
+            out(`         ima2 skill <name> refs     List reference modules`);
+            out(`         ima2 skill install [<name>] --dir <path>\n`);
+        }
+        return;
+    }
+    // Determine which skill to read
+    let skillName = "ima2";
+    let wantPath = false;
+    let wantRefs = false;
+    let wantRef = null;
+    if (positional.length > 0 && positional[0] !== "path" && positional[0] !== "refs" && positional[0] !== "ref" && KNOWN_SKILLS[positional[0]]) {
+        skillName = positional[0];
+        if (positional[1] === "path")
+            wantPath = true;
+        else if (positional[1] === "refs")
+            wantRefs = true;
+        else if (positional[1] === "ref" && positional[2])
+            wantRef = positional.slice(2).join("/");
+    }
+    else if (positional[0] === "path") {
+        wantPath = true;
+    }
+    else if (positional[0] === "refs") {
+        wantRefs = true;
+    }
+    else if (positional[0] === "ref" && positional[1]) {
+        wantRef = positional.slice(1).join("/");
+    }
+    const targetPath = resolveSkillPath(skillName);
+    if (wantPath) {
+        out(targetPath);
+        return;
+    }
+    const skillDir = dirname(targetPath);
+    // ima2 skill <name> refs — list reference modules
+    if (wantRefs) {
+        const refs = discoverRefs(skillDir);
+        if (refs.length === 0) {
+            if (args.json) {
+                json({ skill: skillName, refs: [] });
+            }
+            else {
+                out(`\n  No reference modules for skill "${skillName}".\n`);
+            }
+            return;
+        }
+        if (args.json) {
+            json({
+                skill: skillName,
+                refs: refs.map((r) => ({
+                    name: r.name,
+                    file: r.relPath,
+                    lines: r.lines,
+                })),
+            });
+        }
+        else {
+            out(`\n  Reference modules for "${skillName}" (${refs.length} files):\n`);
+            for (const r of refs) {
+                out(`    ${r.name.padEnd(30)} ${String(r.lines).padStart(4)} lines`);
+            }
+            out(`\n  Load one:  ima2 skill ${skillName} ref <name>`);
+            out(`  Install:   ima2 skill install ${skillName} --dir <path>\n`);
+        }
+        return;
+    }
+    // ima2 skill <name> ref <refname> — print one reference module
+    if (wantRef) {
+        const ref = resolveRef(skillDir, wantRef);
+        if (!ref) {
+            const refs = discoverRefs(skillDir);
+            const available = refs.map((r) => r.name).join(", ");
+            die(2, `reference "${wantRef}" not found in skill "${skillName}". Available: ${available}`);
+        }
+        const content = readFileSync(ref.absPath, "utf-8");
+        if (args.json) {
+            json({
+                skill: skillName,
+                ref: ref.name,
+                file: ref.relPath,
+                lines: ref.lines,
+                content,
+            });
+        }
+        else {
+            out(content.replace(/\n$/, ""));
+        }
+        return;
+    }
+    // --with-refs: bundle SKILL.md + all reference modules (hidden, discouraged)
+    if (args["with-refs"]) {
+        const content = readSkill(targetPath);
+        // Inline bundle — kept for backward compat but not recommended
+        const refs = discoverRefs(skillDir);
+        let bundled = content.replace(/\n$/, "");
+        if (refs.length > 0) {
+            bundled += "\n\n---\n\n# Bundled Reference Modules\n";
+            for (const ref of refs) {
+                const rc = readFileSync(ref.absPath, "utf-8").replace(/\n$/, "");
+                bundled += `\n## [ref: ${ref.name}] (${ref.relPath})\n\n${rc}\n`;
+            }
+        }
+        process.stderr.write("  hint: prefer 'ima2 skill install --dir <path>' — agents read references natively from disk.\n");
+        if (args.json) {
+            json({
+                name: skillName === "ima2" ? "ima2" : `ima2-${skillName}`,
+                format: "markdown-skill-bundled",
+                formatVersion: "1",
+                packageVersion: readPackageVersion(),
+                path: relative(ROOT, targetPath),
+                refCount: discoverRefs(skillDir).length,
+                source: "package",
+                content: bundled,
+            });
+        }
+        else {
+            out(bundled.replace(/\n$/, ""));
+        }
         return;
     }
-    const content = readSkill();
+    const content = readSkill(targetPath);
     if (args.json) {
         json({
-            name: "ima2",
+            name: skillName === "ima2" ? "ima2" : `ima2-${skillName}`,
             format: "markdown-skill",
             formatVersion: "1",
             packageVersion: readPackageVersion(),
-            path: relative(ROOT, SKILL_PATH),
+            path: relative(ROOT, targetPath),
             source: "package",
             content,
         });

package/bin/ima2.js

@@ -315,9 +315,21 @@ function showHelp() {
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)
-    skill          Print packaged agent skill      (ima2 skill --help)
     ping           Ping running server / check health
 
+  Agent skills (SKILL.md + references/):
+    skill ls                         List packaged skills (ima2, front, uiux)
+    skill [front|uiux]               Print a skill's SKILL.md
+    skill [front|uiux] refs          List reference modules
+    skill [front|uiux] ref <name>    Print one reference module
+    skill install --dir <path>       Install all skills to a directory
+    skill install front --dir <path> Install one skill only
+    skill install --tmp              Install to temp dir (ephemeral)
+
+    Skills ship as directories (SKILL.md + references/). The agent resolves
+    its own skill path and passes it via --dir. After install, the agent
+    reads SKILL.md and follows references/ natively from disk.
+
   Options:
     -v, --version  Show version
     -h, --help     Show help
@@ -341,7 +353,15 @@ function showHelp() {
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     ima2 video "a cat playing piano" --duration 10
     ima2 ls -n 10                    Last 10 generations
-    ima2 skill                       Print agent usage skill
+    ima2 skill                       Print core agent skill
+    ima2 skill ls                     List all skills (core, front, uiux)
+    ima2 skill front                  Print frontend implementation skill
+    ima2 skill uiux                   Print design direction skill
+    ima2 skill front refs             List frontend reference modules
+    ima2 skill front ref motion       Load one reference module
+    ima2 skill install --dir <path>   Install all skills
+    ima2 skill install front --dir <path>  Install frontend skill only
+    ima2 skill install --tmp          Install to temp dir
     ima2 capabilities --json         Inspect supported models/options
     ima2 defaults --json             Inspect running server defaults
     ima2 ping                        Health check

package/bin/lib/doctor-checks.js

@@ -63,10 +63,12 @@ export async function buildHardeningDoctorLines({ root, configFile, fileConfig,
         kind: "info",
         text: `Card News: ${runtimeConfig.features.cardNews ? "enabled" : "disabled"}`,
     });
-    const skillPath = join(root, "skills", "ima2", "SKILL.md");
-    lines.push(existsSync(skillPath)
-        ? { kind: "pass", text: `packaged skill found: ${skillPath}` }
-        : { kind: "fail", text: `packaged skill missing: ${skillPath}` });
+    for (const skillDir of ["ima2", "ima2-front", "ima2-uiux"]) {
+        const skillPath = join(root, "skills", skillDir, "SKILL.md");
+        lines.push(existsSync(skillPath)
+            ? { kind: "pass", text: `packaged skill found: ${skillPath}` }
+            : { kind: "fail", text: `packaged skill missing: ${skillPath}` });
+    }
     lines.push(probeBetterSqlite(root));
     const perm = configPermissionLine(configFile, fileConfig);
     if (perm)

package/config.js

@@ -73,6 +73,7 @@ export const config = {
         // Accept both IMA2_PORT and legacy PORT.
         port: pickInt(firstDefined(env.IMA2_PORT, env.PORT), fileCfg.server?.port, 3333),
         host: pickStr(env.IMA2_HOST, fileCfg.server?.host, "127.0.0.1"),
+        lanToken: env.IMA2_LAN_TOKEN || "",
         bodyLimit: pickStr(env.IMA2_BODY_LIMIT, fileCfg.server?.bodyLimit, "50mb"),
     },
     limits: {

package/docs/CLI.md

@@ -34,9 +34,24 @@ Agents should start from the packaged skill and capability commands instead of g
 
 | Command | Description |
 |---|---|
-| `ima2 skill` | Print the packaged Markdown skill from `skills/ima2/SKILL.md` |
-| `ima2 skill --json` | Print a JSON wrapper around the Markdown skill content |
-| `ima2 skill path` | Print the installed skill file path |
+| `ima2 skill` | Print the core Markdown skill (`skills/ima2/SKILL.md`) |
+| `ima2 skill front` | Print the frontend implementation skill (`skills/ima2-front/SKILL.md`) |
+| `ima2 skill uiux` | Print the design direction skill (`skills/ima2-uiux/SKILL.md`) |
+| `ima2 skill ls` | List all available packaged skills |
+| `ima2 skill --json` | Print a JSON wrapper around the core skill content |
+| `ima2 skill front --json` | Print a JSON wrapper around the frontend skill |
+| `ima2 skill uiux --json` | Print a JSON wrapper around the design skill |
+| `ima2 skill path` | Print the core skill file path |
+| `ima2 skill front path` | Print the frontend skill file path |
+| `ima2 skill uiux path` | Print the design skill file path |
+| `ima2 skill front refs` | List reference modules for the frontend skill (names + line counts) |
+| `ima2 skill uiux refs` | List reference modules for the design skill |
+| `ima2 skill front ref <name>` | Print one reference module by name (e.g. `motion`, `stacks/react`) |
+| `ima2 skill uiux ref <name>` | Print one reference module by name (e.g. `design-isms`) |
+| `ima2 skill install --dir <path>` | Install all skills to agent's skill directory |
+| `ima2 skill install --tmp` | Install to `$TMPDIR/ima2-skills/` (ephemeral fallback) |
+| `ima2 skill front refs --json` | JSON list of reference modules |
+| `ima2 skill front ref motion --json` | JSON wrapper around one reference module |
 | `ima2 capabilities --json` | Print supported commands, model/quality/reasoning values, and advisory limits |
 | `ima2 defaults --json` | Print the running server's effective model/reasoning defaults, falling back to local config when no server is reachable |
 | `ima2 defaults --local --json` | Print local effective defaults without contacting the server |
@@ -404,6 +419,13 @@ ima2 storage status --json
 
 # Config
 ima2 skill --json
+ima2 skill ls
+ima2 skill front --json
+ima2 skill uiux path
+ima2 skill front refs
+ima2 skill front ref motion
+ima2 skill install --dir ~/.codex/skills
+ima2 skill install --tmp
 ima2 capabilities --json
 ima2 defaults set model gpt-5.5
 ima2 defaults set reasoning high

package/docs/PROMPT_STUDIO.ko.md

@@ -109,3 +109,32 @@ v1.1.13 Prompt Studio 문제를 고치면서 아래 동작을 계약으로 고
 
 ChatGPT 쿠키, OAuth token 파일, API key, raw upstream response, private prompt
 history, generated base64 data는 공유하지 마세요.
+
+## 캔버스 노트와 i2i 편집
+
+캔버스에서 메모(노트)·화살표·박스를 그리고 저장하면, 노트는 **픽셀이 아니라
+텍스트 지시**로 모델에 전달됩니다.
+
+- 캔버스 버전을 저장하면 주석이 구워진 이미지는 UI 표시/기록용으로만 남고,
+  모델 참조에는 항상 **깨끗한 원본**이 들어갑니다. 현재 이미지를 참조로
+  추가하는 동작도 캔버스 버전이면 원본으로 대체됩니다.
+- 노트 내용은 "캔버스 노트" 칩으로 작성창에 붙습니다. 다음 생성 요청이 이
+  지시문(위치 + 내용 + 마크업 제거 규칙)을 함께 보냅니다. 칩은 언제든 지울
+  수 있습니다.
+- 박스를 그린 뒤 마스크 편집을 실행하면 깨끗한 원본 + 박스 마스크 + 노트
+  지시문으로 편집 API를 호출합니다.
+
+그래도 결과물에 노트/마크업이 남으면:
+
+- 노트 문구를 "무엇을 없앨지"가 아니라 **그 자리에 무엇이 보여야 하는지**로
+  적어 보세요. 예: "포스트잇 제거" 대신 "포스트잇이 있던 자리에 연속된 나무
+  책상 표면이 보이게".
+- 같은 요청으로 여러 후보를 생성해 가장 깨끗한 결과를 고르세요.
+- 남은 흔적만 다시 박스로 지정해 한 번 더 편집하세요.
+
+### 구워진 노트 되돌리기
+
+노트가 구워진 캔버스 버전에서는 **구워진 노트 되돌리기**를 사용할 수 있습니다.
+이후 픽셀 편집이 없으면 깨끗한 원본을 복원하고 저장 당시 노트를 편집 가능한
+초안으로 되살립니다. 배경 정리 등 픽셀 편집이 뒤에 추가됐다면, 되돌릴 때 해당
+편집도 사라지므로 먼저 확인합니다.

package/docs/PROMPT_STUDIO.md

@@ -115,3 +115,34 @@ When opening an issue, include:
 
 Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream
 responses, private prompt history, or generated base64 data.
+
+## Canvas Notes And I2I Editing
+
+When you draw memos (notes), arrows, or boxes on the canvas and save, the
+notes reach the model as **text instructions, not pixels**.
+
+- Saving a canvas version keeps the burned-in annotated image for UI display
+  and history only; model references always use the **clean source**. Adding
+  the current image as a reference also swaps a canvas version for its
+  original.
+- Note contents attach to the composer as a removable "Canvas notes" chip, so
+  the next generation carries the instructions (position + content + a
+  markup-removal rule).
+- Drawing boxes and running the mask edit calls the edit API with the clean
+  source, a box mask, and the note instructions.
+
+If markup still shows up in a result:
+
+- Phrase notes as **what should be visible in that spot**, not only what to
+  remove. For example, "show the continuous wooden desk surface where the
+  sticky note was" instead of "remove the sticky note".
+- Generate several candidates from the same request and pick the cleanest.
+- Box only the residual trace and run one more mask edit.
+
+### Reverting Baked Notes
+
+Canvas versions that contain baked notes offer **Revert baked notes**. When no
+later pixel edit was added, the clean source is restored and the saved notes
+return as an editable draft. If background cleanup or another pixel edit was
+added afterward, Prompt Studio asks for confirmation because reverting also
+discards those pixel edits.

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 207 (runtime: 73, contract: 134)
+Total: 213 (runtime: 76, contract: 137)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -15,11 +15,14 @@ Total: 207 (runtime: 73, contract: 134)
 - `tests/agent-mode-runtime-contract.test.ts`
 - `tests/agent-mode-slash-command-contract.test.ts`
 - `tests/agent-mode-ux-feedback-contract.test.ts`
+- `tests/agent-queue-store-contract.test.ts`
 - `tests/agent-video-intent.test.ts`
 - `tests/agy-artifact-fallback.test.ts`
 - `tests/agy-cli.test.ts`
 - `tests/api-cache-policy.test.ts`
 - `tests/api-provider-parity.test.ts`
+- `tests/backend-hardening.test.ts`
+- `tests/backend-input-lan-hardening.test.ts`
 - `tests/billing-source.test.ts`
 - `tests/card-news-contract.test.ts`
 - `tests/card-news-template.test.ts`
@@ -92,6 +95,7 @@ Total: 207 (runtime: 73, contract: 134)
 - `tests/async-capacity-retry-behavior.test.ts`
 - `tests/async-capacity-retry-contract.test.js`
 - `tests/async-stream-subscribe-order.test.js`
+- `tests/backend-hardening-contract.test.js`
 - `tests/background-cleanup-brush-rasterize.test.js`
 - `tests/background-cleanup-mask-compose.test.js`
 - `tests/bin.test.js`
@@ -99,6 +103,7 @@ Total: 207 (runtime: 73, contract: 134)
 - `tests/browser-attention-badge-contract.test.js`
 - `tests/canvas-alpha-controls-contract.test.js`
 - `tests/canvas-annotation-contract.test.js`
+- `tests/canvas-annotation-revert-contract.test.js`
 - `tests/canvas-apply-merged-contract.test.js`
 - `tests/canvas-background-cleanup-2x2-contract.test.js`
 - `tests/canvas-background-cleanup-contract.test.js`
@@ -212,6 +217,7 @@ Total: 207 (runtime: 73, contract: 134)
 - `tests/toast-stack-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
 - `tests/video-continuity-ui-contract.test.js`
+- `tests/video-defaults-persistence-contract.test.js`
 - `tests/video-gallery-refresh-contract.test.ts`
 - `tests/video-ui-source-count.test.ts`
 - `tests/vite-dev-port-contract.test.js`