@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/canvas-design/canvas-fonts/Tektur-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2023 The Tektur Project Authors (https://www.github.com/hyvyys/Tektur)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/.claude/skills/canvas-design/canvas-fonts/YoungSerif-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2023 The Young Serif Project Authors (https://github.com/noirblancrouge/YoungSerif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: code-review
+description: Evidence-first code review workflow for review, audit, PR feedback, regression checks, and pre-merge quality verification. Use when asked to review changes, audit quality, find risks, or validate external review comments.
+---
+
+# Code Review
+
+## Overview
+
+Review is not performance. Do not invent issues. Do not rubber-stamp code.
+
+**Core principle:** every finding must be grounded in codebase evidence.
+
+## Use This Skill For
+
+- review this change
+- audit this diff
+- check for bugs/regressions
+- validate PR quality before merge
+- verify external review comments
+
+## Review Order
+
+Check in this order:
+
+1. **Correctness**
+   - does the code actually implement the requested behavior?
+   - are there obvious broken paths, stale refs, wrong assumptions, or missing cases?
+
+2. **Regression risk**
+   - what existing behavior could this break?
+   - are touched shared paths/tests/contracts still aligned?
+
+3. **Safety / security / data loss**
+   - destructive actions
+   - auth/permission checks
+   - path handling
+   - unsafe shell / DB / file operations
+
+4. **Performance / scale**
+   - accidental N+1, repeated I/O, redundant parsing, large scans inside hot paths
+
+5. **Maintainability**
+   - duplicated logic
+   - dead branches
+   - misleading naming
+   - drift between docs/tests/source
+
+## Workflow
+
+### 1. Gather minimal context
+
+- Read the diff or changed files first
+- For non-trivial reviews, use index-first context:
+  - open primary target(s)
+  - open 1-2 analog/shared files when needed
+  - open related tests if behavior is covered
+
+### 2. Verify each concern against reality
+
+Before raising a finding:
+- point to the exact file and lines
+- explain the concrete failure mode
+- verify it is not already handled elsewhere
+
+If a comment from another reviewer looks questionable:
+- check the actual codebase behavior first
+- do not accept it blindly
+
+## What Makes a Good Finding
+
+A good finding includes:
+- **where** the issue is
+- **why** it matters
+- **when/how** it fails
+- **what severity** it deserves
+
+Good:
+- “This cache reuse key ignores file moves, so renames keep stale entries until manual cleanup.”
+
+Bad:
+- “This could maybe be cleaner.”
+
+## Severity Guide
+
+- **P0** — data loss, security break, destructive wrong behavior
+- **P1** — likely bug / broken common path / high regression risk
+- **P2** — meaningful but narrower correctness/maintainability issue
+- **P3** — minor cleanup or polish
+
+## Review Rules
+
+- Prefer **few precise findings** over many weak ones
+- If no real issue is found, say so
+- Do not demand refactors without concrete payoff
+- Do not call style preference a bug
+- If source contradicts docs, source wins — note doc drift separately if relevant

package/templates/.claude/skills/debugging-toolkit/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: debugging-toolkit
+description: Comprehensive debugging methodology combining systematic investigation (4 phases) with deep-dive root cause tracing - use for runtime bugs, crashes, and unexpected behavior (not test writing) to ensure root cause is found before fixing
+---
+
+# Debugging Toolkit
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues. This toolkit combines systematic investigation with deep tracing techniques.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**The Iron Law:**
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+
+**Especially when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- Bug appears deep in the stack trace
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+
+4. **Root Cause Tracing (Deep Dive)**
+
+   **Use when error is deep in call stack:**
+
+   **The Tracing Process:**
+   1. **Observe Symptom:** `Error: git init failed in /packages/core`
+   2. **Find Immediate Cause:** `execFile('git', ['init'], { cwd: '' })`
+   3. **Trace Upwards:**
+      - Who called this? `WorktreeManager`
+      - With what arguments? `projectDir = ''`
+   4. **Find Original Trigger:**
+      - Where did empty string come from? `setupCoreTest()` returned empty `tempDir`
+   5. **Fix at Source:** Fix `setupCoreTest`, NOT the immediate caller.
+
+   **Instrumentation:**
+   If manual tracing fails, add logging *before* the failure:
+   ```js
+   console.error('DEBUG context:', {
+     arg: someArg,
+     stack: new Error().stack // crucial!
+   });
+   ```
+
+5. **Gather Evidence in Multi-Component Systems**
+   - Log what enters/exits each component boundary
+   - Verify environment/config propagation
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - Read reference implementation COMPLETELY
+   - Don't skim - read every line
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis (don't stack fixes)
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - **MUST** have before fixing
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If ≥ 3: **STOP and question the architecture**
+   - Discuss with your human partner before attempting Fix #4
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "One more fix attempt" (when already tried 2+)
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, trace stack backwards | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |

package/templates/.claude/skills/delivery/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: delivery
+description: Project delivery workflow and quality gates for UKit templates.
+---
+
+# Delivery Skill
+
+Project: {{project.name}} | Stack: {{project.stack}}
+
+## Execution Rules
+
+- Act first, explain after. Smallest correct change set.
+- Review gate for non-trivial edits (>3 files or >50 lines).
+- Reuse existing code. No drive-by refactors.
+
+## Docs-Centric Principle
+
+**Docs are the center.** Read docs first, write docs last.
+Token cost is acceptable: accurate docs prevent wasted debugging cycles and wrong root cause guesses.
+**Source is always truth.** If source contradicts docs → update docs immediately before continuing.
+
+Docs reading is **graduated by task size**:
+- Trivial (< 30s): skip docs entirely.
+- Simple (1 file, clear scope): `MEMORY.md` only — quick constraints check.
+- Non-trivial (multi-file, unclear scope, bugs): full Tier 1 sequence below.
+
+## 3-Tier Reading Strategy
+
+Read in order. Never skip to Tier 3 without Tier 1+2.
+
+**Tier 1 — Docs** (always first, cheapest context):
+- `docs/MEMORY.md` → decisions, constraints, known bugs, open risks
+- `docs/PROJECT.md` → architecture, business rules, dangerous areas
+- `docs/CODE_MAP.md` → structural index (if it exists)
+- Recent `docs/WORKLOG.md` → when continuing prior work or debugging
+
+**Tier 2 — Structure Scan** (before opening source files):
+- Glob file tree → know what exists where
+- Grep function/class/export signatures → understand shape without full reads
+- Narrows exactly which files to open in Tier 3
+
+**Tier 3 — Targeted Source Reads** (only what is needed):
+- Read only the specific files relevant to the task
+- If source contradicts docs → **source wins, update docs before proceeding**
+
+## Docs Discipline
+
+After any non-trivial task, AI must update docs proactively — **do not wait to be asked**:
+
+- **MEMORY.md** ⭐ — **most critical**. Always ask after any task: "What did I learn about this system?" Write it if durable: new decision, constraint, bug pattern, open risk, or handoff note.
+- **WORKLOG** — always: date, what was done, files changed, verification, outcome
+- **PROJECT.md** — when: new module added, business rule clarified, dangerous area identified
+- **CODE_MAP.md** — when: module structure changes, new integration added, new dangerous area found
+
+**AI must infer docs content from source**, not wait for user to dictate it. If a section is empty, read source and fill it in. If docs are stale, update them to match source before continuing.
+
+## Workflow
+
+1. **Orient** — Tier 1: read docs, form hypothesis about the system
+2. **Scan** — Tier 2: Glob + Grep to verify hypothesis, find relevant files
+3. **Verify** — if source contradicts docs, update docs first
+4. **Execute** — smallest change, follow existing patterns
+5. **Test** — run tests, check regressions
+6. **Document** — update WORKLOG + any stale/missing docs sections
+
+## Docs Noise — Smart Compact
+
+Docs grow over time and become noisy. AI must manage this proactively:
+
+**WORKLOG** — when it exceeds ~100 lines:
+- Summarize entries older than 2 weeks into a single line in `MEMORY.md` → Completed Milestones
+- Keep only the last 2–3 weeks of detail in WORKLOG
+- Do this during the Document step, not as a separate task
+
+**MEMORY.md** — when sections become stale:
+- Remove resolved risks from Open Risks
+- Archive outdated decisions to a `## Archived Decisions` section at the bottom
+- Merge duplicate bug entries into a single pattern note
+- Keep each section scannable in < 10 lines — if longer, consolidate
+
+**CODE_MAP.md** — when it drifts from source:
+- During Tier 2 scan, if you find the map is wrong or missing entries → fix it before continuing
+- Remove entries for deleted modules; add entries for new ones discovered
+
+**Principle**: Docs should always be shorter than source code and faster to read than scanning files. If reading docs takes longer than a Grep scan, the docs are too noisy.
+
+## Quality
+
+- No regressions. Security basics. No debug code in production.
+- Only change what was requested.
+
+Provider: UNIC

package/templates/.claude/skills/discover-security/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: discover-security
+description: Project-local security workflow for authentication, authorization, input validation, secrets, shell/file safety, database safety, and security review. Use for security-sensitive coding, audits, OWASP-style hardening, and risky data/auth changes.
+---
+
+# Security Workflow
+
+## Overview
+
+Security work should stay **project-local, evidence-first, and minimal-scope**.
+
+This skill exists so a UKit-installed project can handle common security-sensitive work **without depending on external home-directory skills**.
+
+## Use This Skill For
+
+- auth / authorization changes
+- secrets / credentials / tokens
+- input validation / sanitization
+- SQL injection / XSS / command injection risk
+- file-system safety / path traversal / dangerous shell usage
+- security review / hardening / audit
+- risky migration / uninstall / destructive flows
+
+## First Moves
+
+1. **Treat the task as non-trivial by default**
+2. Use **index-first context**
+   - open primary target(s)
+   - open related tests
+   - open shared abstractions
+3. If review/audit is requested, also read:
+   - `.claude/skills/code-review/SKILL.md`
+
+## Security Review Checklist
+
+Check these areas in order:
+
+### 1. Trust boundaries
+- what input is user-controlled?
+- what crosses API / DB / shell / filesystem boundaries?
+
+### 2. Authorization
+- is access checked in the right place?
+- can a caller reach this path without required permission?
+
+### 3. Input handling
+- validate shape, type, and allowed values
+- reject dangerous or ambiguous inputs early
+- avoid “sanitize later” logic
+
+### 4. Dangerous execution surfaces
+- shell command construction
+- SQL string concatenation
+- path joins / traversal
+- deletes / recursive writes / destructive mutations
+
+### 5. Secrets and sensitive data
+- no secrets in logs, docs, tests, or committed config
+- no tokens/passwords echoed unnecessarily
+
+### 6. Regression risk
+- what existing safe behavior could this weaken?
+- are related tests covering the dangerous path?
+
+## UKit-Specific Guidance
+
+When reviewing or changing UKit internals, pay special attention to:
+- install/uninstall safety
+- path traversal protection
+- symlink handling
+- manifest validation
+- hook auto-allow logic
+- index commands that execute shell or parse project files
+
+## Pairing Guidance
+
+- For **security review** → pair with `.claude/skills/code-review/SKILL.md`
+- For **bug investigation** → pair with `.claude/skills/debugging-toolkit/SKILL.md`
+- For **test coverage around a fix** → pair with `.claude/skills/testing-quality/SKILL.md`
+
+## Rules
+
+- prefer narrow, structural protections over ad-hoc patching
+- fix unsafe behavior at the earliest boundary possible
+- do not approve risky code without a concrete failure model
+- if a change increases destructive power, require stronger evidence and verification

package/templates/.claude/skills/docker-packaging/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: docker-packaging
+description: Containerization workflow for Dockerfile, .dockerignore, compose.yaml/docker-compose.yml, multi-stage builds, healthchecks, service dependencies, env handling, and runnable Docker packages. Use when asked to containerize an app, add or fix Docker/Compose, package a repo to run in Docker, or prepare local/dev/prod container workflows.
+enabledByDefault: false
+---
+
+# Docker Packaging
+
+Use this skill when the task is about:
+- creating or fixing a `Dockerfile`
+- adding `.dockerignore`
+- creating or fixing `compose.yaml` / `docker-compose.yml`
+- packaging an app so it runs locally or in deployment via Docker
+- tightening container startup, healthchecks, env wiring, or dependency services
+
+## Default workflow
+
+1. Inspect the repo first:
+   - runtime and package manager
+   - real build/start commands
+   - ports
+   - env files / required variables
+   - DB/cache/queue dependencies
+   - generated build output vs source-run mode
+2. Prefer the smallest reliable image and a multi-stage build.
+3. Add `.dockerignore` whenever a Docker build is introduced.
+4. Use Compose only when the app needs multiple services or the user explicitly asks for it.
+5. Keep the generated package runnable with the repo’s actual commands; do not invent fake entrypoints.
+
+## Build rules
+
+- Prefer official runtime images unless the repo clearly needs something else.
+- Separate dependency install, build, and runtime stages when the stack benefits from it.
+- Keep runtime images free of dev-only tooling when possible.
+- Prefer non-root runtime users when the base image already supports it cleanly.
+- Copy manifests / lockfiles before source code to preserve dependency-layer cache.
+- Respect the repo’s native package manager and lockfile.
+- For frontend builds, serve the real built output; do not leave dev servers in production images unless the user explicitly wants a dev container.
+
+## Compose rules
+
+- Prefer `compose.yaml` for new files; preserve an existing `docker-compose.yml` if the repo already uses it.
+- Add only the services the app truly needs.
+- Use healthchecks when startup order matters.
+- Wire service names, ports, and env variables consistently with the app config.
+- Use named volumes only when persistence or local live-edit mounting is actually useful.
+- Do not hardcode secrets; use `.env`, `env_file`, or placeholder variables.
+
+## Verification
+
+- Verify against repo reality:
+  - build command
+  - runtime command
+  - exposed port
+  - dependency services
+- Prefer lightweight checks first:
+  - `docker build`
+  - `docker compose config`
+  - targeted smoke command for the real app entry
+- If UKit’s source-code index is available, use it first to find entrypoints, ports, config files, and related services before drafting Docker assets.