@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/skills/fec-dependency-upgrade/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/skills/fec-dependency-upgrade/references/engineering-practices.md

@@ -0,0 +1,73 @@
+---
+practiceCards:
+  - id: "fec-dependency-upgrade:compatibility"
+    level: "recommended"
+    sourceIds: ["google-review","typescript-publishing"]
+    caseIds: ["EP-TS-01"]
+    evidence: "review-only"
+  - id: "fec-dependency-upgrade:artifact-consumer"
+    level: "required"
+    sourceIds: ["typescript-publishing","ms-playbook"]
+    caseIds: ["EP-TS-01","EP-UI-01"]
+    evidence: "review-only"
+---
+
+# Local engineering decisions
+
+Locate the actual role, toolchain and existing conventions, then read relevant [shared principles](common/engineering-practices.md). These conditions apply to this entry, not every project. Structure checks do not prove all semantics or execution.
+
+<a id="fec-dependency-upgrade:compatibility"></a>
+## Upgrade against evidenced compatibility needs
+
+Level: recommended
+
+### Risk
+An isolated guide’s preferred version can expand a small task into a breaking toolchain migration.
+
+### Applies
+For dependency/framework upgrades and security fixes with an actual project need.
+
+### Decision
+Read manifest/lock, peer requirements, supported engines and migration notes. Choose a scoped compatible change, preserve rollback and document behavior/type/build impacts.
+
+### Exceptions
+A docs page showing a newer release is not authorization to upgrade. An example-only dependency stays isolated from CLI/product runtime dependencies.
+
+### Examples
+Better: pin a compatible DOM test environment in its own example. Worse: upgrade project Node/React/build tools only to run the example.
+
+### Verification
+Use current lint/type/build tests plus affected consumers and actual artifact checks; record unsupported environments rather than hiding them.
+
+### Sources
+google-review, typescript-publishing — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-TS-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.
+
+<a id="fec-dependency-upgrade:artifact-consumer"></a>
+## The packed dependency is the delivery contract
+
+Level: required
+
+### Risk
+Workspace success can conceal missing declarations, examples, locks or runtime files.
+
+### Applies
+For shipped packages and upgrades that change their consumed surface.
+
+### Decision
+Inspect actual tarball contents and exact version/integrity, install away from sibling sources, and validate supported consumers. Keep generated common content authoritative and coordinated across products.
+
+### Exceptions
+Do not overwrite a consumed/published version with different bytes or relax ownership checks to force an upgrade. Unpublished local candidates require explicit local evidence, not public-download claims.
+
+### Examples
+Better: both products consume the same immutable common archive/SRI. Worse: a file/link path to a neighbor silently supplies missing content.
+
+### Verification
+Run real packaging/consumer checks, compare source bytes and preserve user edits through migration. A passing React sample alone does not prove all distribution formats.
+
+### Sources
+typescript-publishing, ms-playbook — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-TS-01, EP-UI-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.

package/skills/fec-doc-sync/SKILL.md

@@ -3,37 +3,16 @@ name: fec-doc-sync
 description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, lockfiles, config, env examples, routes, API clients or server routes, schemas, components, tests, CI, build/deploy config, ADRs, changelogs, or migration notes. Do not use for general prose polishing only; Chinese triggers include document synchronization, update README, docs sync, environment variable documentation, command list, API Document synchronization.
 ---
 
-# Document synchronization
+# Frontend documentation synchronization
 
-## Purpose
+Follow the [common documentation method](references/common/doc-sync.md) for evidence, multilingual consistency and delivery records.
 
-Synchronize front-end project documentation from code, configuration, tests, types, scripts and runtime templates to avoid README, docs, environment variable descriptions, API/routing descriptions, architectural decisions and migration notes from drifting from actual project behavior.
+## Frontend facts
 
-## Procedure
+Inspect package.json, lockfiles, framework/build configuration, env examples, routes, API clients/server routes, types/schemas, components, tests, CI and deployment files.
 
-1. Identify the project stack, document entry and the scope that needs to be synchronized this time; README synchronization must scan the root directory `README*`, `docs/*/README*`, package, application, deployment or runtime related README, and exclude `node_modules`, build products and third-party dependency directories.
-2. Gather sources of truth: `package.json`, lockfile, framework and build configurations, `.env.example`, routes, API clients or server routes, types/schemas, components, tests, CI, build/deploy config.
-3. Compare commands, environment variables, routes, API behaviors, deployment steps and support matrix in README, docs, ADR, changelog, example prompts, setup/deploy/env docs.
-4. Only update stable public conventions; do not write temporary debugging conclusions, one-time reports or unimplemented designs into long-term documents.
-5. If the warehouse already has multilingual documents or internationalized README, after updating the public facts of the main README, you must check whether other language READMEs need to be synchronized; function names, command names, script names, package names, component/API names, report file names, paths, environment variables, routing/API names, version constraints, and support matrices must be consistent across languages.
-6. Product copy can maintain localized expression, but must not retain old facts, old default recommendations, or expired examples; when high-quality translation is not possible, at least synchronize key facts, and mark the risks of manual translation in the output.
-7. When the project exposes plug-ins, SDKs, CLIs, component libraries, templates or integration capabilities, synchronize the corresponding function list, integration instructions, command/script instructions, public metadata, example prompt words or example usage.
-8. Run relevant documentation consistency, legacy searches, report format consistency, type checks, testing, build or packaging checks.
+## Frontend synchronization scope
 
-## Constraints
+Check root, package, application, deployment and runtime READMEs, docs, ADRs, changelogs, environment and setup guides. Compare routing/API behavior, client integration, support matrices, plugin entry points, commands, report paths, metadata and example prompts.
 
-- Do not turn README into complete implementation details; public documentation retains high-signal summaries.
-- Do not introduce command, path, environment variable, API behavior, or capability names that are inconsistent with the source of truth.
-- Do not write unconfirmed TODOs, drafts, or experimental capabilities as supported behavior.
-- Do not modify user project private documents unless explicitly specified by the user.
-- If multi-language documents cannot be fully translated, at least keep the command names, environment variables, route/API names, version constraints and report formats consistent.
-- Do not reduce internationalized README synchronization to just the main README; public facts, feature lists, report lists, command/script descriptions, and example usage must check all language entries.
-- Do not treat ADR as a long review; only record the background, decisions, trade-offs, scope of impact, verification and rollback clues.
-
-## Expected Output
-
-- List synchronized README/docs/ADR/changelog/env/setup/deploy documents.
-- List the checked README/docs entries and indicate which language files have been synchronized, which do not need to be synchronized, and which require manual confirmation.
-- Summarize the sources of truth used, update scope, verification orders, and non-coverage risks.
-- Aggregate legacy caliber searches, report filename/path/command consistency and multilingual key fact consistency verification results.
-- Highlight product copy, translations, external service configurations, or release notes that still require manual confirmation.
+Check public facts in every existing language. Record sources, changed/unchanged documents and translation review needs using the common method. Use the project's existing content, type, test and packaging checks.

package/skills/fec-doc-sync/references/common/doc-sync.md

@@ -0,0 +1,12 @@
+# Documentation synchronization
+
+Synchronize public documentation from implementation facts, not from the desired design.
+
+1. Identify the repository stack, document entry points and requested scope. Include root READMEs, nested package/application/runtime READMEs and deployment guides; exclude dependencies, generated outputs and third-party directories.
+2. Collect authoritative project sources: manifests/lockfiles, configuration, env examples, commands, schemas, public APIs, tests, CI, build and deployment files. Use sources for the actual stack rather than require a particular language's manifest.
+3. Compare commands, environment variable names, paths, versions, API behavior, capabilities, setup and deployment instructions. Keep only stable public facts; do not present proposals or experimental designs as supported behavior.
+4. Check every existing language entry. Public identifiers, commands, version constraints, support matrices, report paths and examples must agree. Translate prose according to the existing convention; explicitly report translations requiring human review.
+5. Update affected README/docs/ADR/changelog and user-facing metadata together. An ADR records context, decision, alternatives, impact, verification and rollback clues; it is not a full review report.
+6. Run the project's existing consistency checks, relevant type/tests/build or packaging checks and legacy-reference search. Record each checked document, source of truth, updated language, unchanged entry and unresolved uncertainty.
+
+Do not invent commands or environment variables, overwrite private documents outside the requested scope, or replace a README with internal implementation details. A successful prose edit alone does not prove factual consistency.

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

@@ -1,81 +1,16 @@
 ---
 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; 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.
+description: Use when generating or editing frontend UI mockups, product images, posters, brand visuals, illustrations, avatars, storyboards, or raster assets, including PNG quality checks. Do not use for structured architecture, sequence, workflow, or data-flow diagrams.
 ---
 
-# Image generation and chart workflow
+# Frontend visual asset generation and editing
 
-## Purpose
+For UI, brand and product visuals, read [asset routing](references/artifact-routing.md). Select generate, edit or hybrid according to available source images, purpose, dimensions, transparency and delivery path.
 
-Generate or edit diagrams, visual assets, and image workflows, and perform reviewable self-checks and repair iterations on exported PNGs.
+## Implementation and quality checks
 
-## Procedure
+Preserve original images and save edits separately by default. Do not present placeholders or concept drafts as final product imagery. Clarify branding, text, accessible alternatives and licensing; prefer targeted edits when suitable source imagery exists.
 
-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.
+Inspect actual PNG output before delivery: verify subject rendering, clipping, composition, transparency and branding. Use the [shared-source PNG checker](scripts/png-qa.mjs). Default to at most two repairs; follow [PNG repair guidance](references/png-qa-autofix.md) to modify source, prompt or layout rather than destructively changing output pixels.
 
-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. 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. 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
-     ```
-   - Still running PNG basic checks without manifest:
-     ```bash
-     node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --format json
-     ```
-
-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. 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
-
-- 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
-
-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.
+Report source and output paths, generation route, QA rounds and unresolved risks. Structured technical diagrams use the dedicated common diagram capability; this entry no longer maintains a technical diagram renderer.

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

@@ -14,9 +14,9 @@
 | ----- | ------ |
 | `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-overlap` | Increase spacing, reflow to grid/layers, split clusters, or wrap complete 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. |
+| `label-overflow` | Wrap text, widen the box, preserve complete copy, and 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. |
@@ -28,3 +28,10 @@ The helper can only reason about overlaps and connectors when the manifest coord
 ## 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.
+
+
+## Quality delivery contract
+
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse cc-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+
+The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.