@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/skills/cc-tauri-project-standard/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/cc-tauri-project-standard/references/engineering-practices.md

@@ -0,0 +1,73 @@
+---
+practiceCards:
+  - id: "cc-tauri-project-standard:ipc-validation"
+    level: "required"
+    sourceIds: ["tauri-permissions"]
+    caseIds: ["EP-TS-01","EP-IPC-01"]
+    evidence: "review-only"
+  - id: "cc-tauri-project-standard:cancellation-cleanup"
+    level: "conditional"
+    sourceIds: ["tokio-join","tauri-permissions"]
+    caseIds: ["EP-RS-01","EP-IPC-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="cc-tauri-project-standard:ipc-validation"></a>
+## Command registration does not grant safe authority
+
+Level: required
+
+### Risk
+A capability file can exist while the selected command/window grants remain wrong.
+
+### Applies
+For actual Tauri2 commands/plugins; inspect the installed minor and selected app configuration.
+
+### Decision
+Check invoke registration, generated app-command permissions, selected/overlapping capabilities, window labels and allowed remote origins. Validate bounded typed input and business permission in Rust before effects.
+
+### Exceptions
+The app owns trusted roots/paths, not the renderer. Canonicalize-then-open alone does not defeat adversarial ancestor replacement. Do not transplant Electron APIs.
+
+### Examples
+Better: one scoped command validates paths under an application-owned root. Worse: renderer supplies an unrestricted root and registration is treated as authorization.
+
+### Verification
+Run the existing Rust core tests and inspect actual generated/configured grants; runtime permission activation and GUI remain separate NOT RUN evidence.
+
+### Sources
+tauri-permissions — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-TS-01, EP-IPC-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.
+
+<a id="cc-tauri-project-standard:cancellation-cleanup"></a>
+## Window shutdown coordinates core tasks and resources
+
+Level: conditional
+
+### Risk
+A closed window can leave Rust work or sidecar resources active.
+
+### Applies
+When commands spawn work or retain files/pools/sidecars beyond invocation.
+
+### Decision
+Name the app/core task owner, stop admission, request cancel/drain and await completion before releasing dependencies. Keep blocking work and guards outside UI-critical suspension where possible.
+
+### Exceptions
+Caller cancellation may not stop a native write; represent incomplete/partially committed work explicitly. Do not force a runtime/dependency upgrade.
+
+### Examples
+Better: core reports completed or incomplete shutdown to the app. Worse: dropping a UI waiter is treated as proof all native work stopped.
+
+### Verification
+Use actual core/runtime event tests and target-specific process checks. Existing path tests and Node IPC evidence do not prove Tauri shutdown or signed bundles.
+
+### Sources
+tokio-join, tauri-permissions — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-RS-01, EP-IPC-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.

package/skills/cc-tauri-project-standard/references/practice.md

@@ -0,0 +1,20 @@
+# Tauri practice
+
+- Read `tauri.conf.json`, `Cargo.toml`, locks, `build.rs`, capabilities, permissions and web build configuration before changing a boundary. Keep related UI/core ownership explicit in a mixed workspace.
+- For Tauri 2 custom app commands, inspect `AppManifest::commands` and generated permissions as well as `invoke_handler`. Registered app commands are not automatically restricted merely by having a capability file. Check the capabilities actually selected in configuration, their overlapping grants, window labels and remote access.
+- Receive bounded typed inputs, validate paths and business permissions in Rust, return stable public errors, and serialize results deliberately. Never accept a renderer-supplied trusted root. The [example core](../examples/minimal/core/src/lib.rs) uses an application-owned root and canonical containment checks.
+- This example assumes an application-owned directory. Canonicalize-then-open is not an adversarial filesystem race defense; use platform handles/open-relative APIs when another local actor can replace ancestors concurrently.
+- Keep the smallest state behind `State`, document ownership of pools/tasks/files, and release it on shutdown. Choose async/blocking boundaries from measured work and actual runtime behavior; avoid blocking the UI or holding a guard across await.
+- Audit plugins, sidecars, command argument construction, CSP and navigation as separate authority surfaces. New windows must not silently inherit broad grants.
+- Preserve build target settings. Linux system libraries, Windows WebView2, macOS signing/entitlements and updater signatures require target-specific evidence.
+
+## Official version references
+
+Checked 2026-11-08 against Tauri **2** documentation; match the project's locked minor/plugins before using version-sensitive APIs:
+
+- [Commands and typed invocation](https://v2.tauri.app/develop/calling-rust/).
+- [Capabilities and app-command permission generation](https://v2.tauri.app/security/capabilities/).
+- [Permission definitions](https://v2.tauri.app/security/permissions/).
+- [Runtime authority](https://v2.tauri.app/security/runtime-authority/).
+
+The example's Rust-only core is a separate crate so its boundary tests can run offline without pretending a Tauri runtime or GUI was exercised.

package/skills/cc-tauri-project-standard/references/verification.md

@@ -0,0 +1,18 @@
+# Verification boundaries
+
+From [the minimal application](../examples/minimal/README.md), run:
+
+```sh
+cargo test --manifest-path core/Cargo.toml --offline --locked --features defective
+cargo test --manifest-path core/Cargo.toml --offline --locked
+```
+
+The first command intentionally fails the same traversal/absolute-path assertions; the second must pass them plus allowed-file behavior. Unix additionally checks a symlink escape. A compiler/dependency failure is MISSING, not the expected business failure. Keep build outputs outside the distributable skill directory.
+
+| Layer | Evidence and limits |
+| --- | --- |
+| Rust command core | Real `cargo test`; invalid paths must fail before returning outside data. No GUI needed. |
+| Tauri integration | With the existing prepared Tauri 2 toolchain, build/run the app and test allowed/denied windows and capabilities through actual invoke calls. Rust unit results do not prove permission activation. |
+| Desktop release | Run UI journeys and target bundles, installation/update, cleanup and signing on each supported OS. No substitution by text checks. |
+
+Development evidence on 2026-11-08: Windows Rust 1.96.0 core tests observed real RED then GREEN. Tauri dependency build, WebView permission activation, GUI, signing and bundles were **NOT RUN**. Report missing system libraries or dependencies without downloading them implicitly.

package/skills/cc-tdd-methodology/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-tdd-methodology
+description: Use when implementing new observable behavior or fixing a behavioral defect through tests, or when deciding whether a change is test-driven development or pure behavior-preserving refactoring.
+---
+
+# Test-driven development
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-tdd-methodology/references/method.md

@@ -0,0 +1,13 @@
+# Test-driven development
+
+For new behavior and behavior-changing defect fixes use RED → GREEN → REFACTOR. The test describes an observable contract, not private implementation structure.
+
+1. Identify one behavior: inputs, output/error, state transition or externally observable side effect. Choose the closest meaningful test level using existing project tooling.
+2. Write the smallest test that distinguishes the missing or wrong behavior. Run it first and observe failure for the expected behavior, not a syntax, import or environment problem. For a defect, the test must fail against the original defect.
+3. Implement only enough to pass that test. Do not refactor during the red phase or add unrelated features.
+4. Run the test and relevant surrounding tests, then improve naming and structure while preserving green. New requirements enter the next cycle.
+5. Report the observed red/green commands, covered behavior and untested boundaries. Do not infer success from a diff or unexecuted tests.
+
+Pure structural refactoring has a different contract: establish current behavior through existing or characterization coverage and keep GREEN → REFACTOR → GREEN. Do not invent a failure merely to satisfy a ritual.
+
+Test logic close to the risk; use integration tests for real boundaries and end-to-end tests for journeys that need them. Do not make E2E the default or assert fragile private state. Do not introduce a new testing framework merely for TDD. If infrastructure is absent, explain the minimum test setup and obtain a decision before introducing it; use the actual stack rather than require frontend tools.

package/skills/cc-technical-diagrams/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cc-technical-diagrams
+description: Use when creating or exporting structured technical diagrams, including architecture, workflows, sequence diagrams, data flows, lifecycle diagrams, agent or memory flows, local interactive previews, and PNG quality checks. Use editable draw.io sources when long-term manual editing or vendor shapes matter. Do not use for UI mockups, product imagery, posters, or raster image editing.
+---
+
+# Technical diagrams
+
+Create complete, readable technical diagrams from editable structured sources. This workflow applies across frontend, backend, infrastructure, and agent systems.
+
+## Choose the source
+
+Read [diagram workflows](references/diagram-workflows.md). Prefer locally available Mermaid for standard sequence and flowcharts. Use HTML technical diagrams for self-contained browser viewing, semantic architecture and agent/memory flows; read [HTML technical diagrams](references/html-technical-diagrams.md). Choose editable draw.io sources for official vendor shapes or long-term manual editing.
+
+Use a local interactive preview when the user benefits from incremental explanation; keep JSON/SVG/PNG exports as deliverables. The live server is [interactive-diagram-server.mjs](scripts/interactive-diagram-server.mjs) and the local page is [interactive-diagram.html](assets/interactive-diagram.html).
+
+## Render and export
+
+Keep every node, relationship, complete label and explicit geometry. The renderer supports workflow, sequence, dataflow, lifecycle and architecture. Never silently simplify advanced sequence semantics; prefer Mermaid for activation and alt/loop/par fragments.
+
+```sh
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input diagram.json --type architecture --output diagram.html --manifest diagram.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input diagram.html --format png --output diagram.png --theme light --scale 2 --manifest diagram.layout.json --output-manifest diagram.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png diagram.png --manifest diagram.actual.json --format json
+```
+
+Standard Mermaid sources use [mermaid-render.mjs](scripts/mermaid-render.mjs). Reuse [diagram-layout.mjs](scripts/diagram-layout.mjs) and [diagram-browser.mjs](scripts/diagram-browser.mjs); do not invent another renderer or add required browser libraries, remote scripts or downloaded icon packs.
+
+## Verify and deliver
+
+Inspect the actual exported image for clipping, text truncation, crossing labels, overlaps and missing content. PNG QA uses the actual scaled export manifest, not the source's estimated coordinates. Successful export alone does not prove visual acceptance. Read [PNG repair guidance](references/png-qa-autofix.md); repair the source or layout, not the output pixels. Default to at most two repair rounds and report unresolved issues.
+
+Deliver JSON/Mermaid source, HTML where relevant, exports and QA evidence. Record tool versions, theme, scale, repair rounds and partial acceptance. Optional Mermaid/Graphviz/browser tools must fail clearly or use an available fallback; do not install them automatically or claim a missing export succeeded. Retain complete labels instead of hiding overflow at higher resolution.
+
+Examples and fixtures: [quality examples](assets/quality-examples/README.md), [sequence JSON](assets/quality-examples/sequence.json), [workflow JSON](assets/quality-examples/workflow.json), [architecture JSON](assets/quality-examples/architecture.json), [invalid explicit geometry](assets/quality-examples/invalid-explicit.json).