@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/verification-loop/scripts/detect-checks.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+// Detects a project's verification commands and prints them as JSON.
+// Usage: node detect-checks.js [project-dir]
+// Read-only: it never runs the commands it finds.
+
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(process.argv[2] || '.');
+const has = (f) => fs.existsSync(path.join(root, f));
+const read = (f) => {
+  try {
+    return fs.readFileSync(path.join(root, f), 'utf8');
+  } catch {
+    return '';
+  }
+};
+const checks = [];
+const add = (kind, command, source) => {
+  if (!checks.some((c) => c.command === command)) checks.push({ kind, command, source });
+};
+
+// JavaScript / TypeScript
+if (has('package.json')) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(read('package.json'));
+  } catch {}
+  const pm = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : has('bun.lockb') || has('bun.lock') ? 'bun' : 'npm';
+  // bun needs `run`: `bun test` / `bun build` are its own runner and bundler, not the scripts.
+  const run = (s) => (pm === 'npm' || pm === 'bun' ? `${pm} run ${s}` : `${pm} ${s}`);
+  const scripts = pkg.scripts || {};
+  const map = [
+    ['build', /^build$/],
+    ['format', /^(format:check|fmt:check|prettier:check|check:format)$/],
+    ['lint', /^(lint|eslint|biome)$/],
+    ['typecheck', /^(typecheck|type-check|tsc|check:types|types)$/],
+    ['test', /^(test|test:unit|vitest|jest)$/],
+    ['test-integration', /^test:(integration|int)$/],
+  ];
+  for (const [kind, re] of map) for (const s of Object.keys(scripts)) if (re.test(s)) add(kind, s === 'test' && pm === 'npm' ? 'npm test' : run(s), 'package.json');
+  if (!Object.keys(scripts).some((s) => /type/.test(s)) && has('tsconfig.json')) add('typecheck', `${pm === 'npm' ? 'npx' : pm + ' exec'} tsc --noEmit`, 'tsconfig.json');
+}
+
+// Python
+if (has('pyproject.toml') || has('setup.cfg') || has('requirements.txt')) {
+  const py = read('pyproject.toml') + read('setup.cfg');
+  const runner = has('uv.lock') ? 'uv run ' : has('poetry.lock') ? 'poetry run ' : '';
+  if (/\[tool\.ruff/.test(py) || has('ruff.toml')) {
+    add('format', `${runner}ruff format --check .`, 'ruff');
+    add('lint', `${runner}ruff check .`, 'ruff');
+  } else if (/flake8/.test(py) || has('.flake8')) add('lint', `${runner}flake8`, 'flake8');
+  if (/\[tool\.black/.test(py)) add('format', `${runner}black --check .`, 'black');
+  if (/\[tool\.mypy/.test(py) || has('mypy.ini')) add('typecheck', `${runner}mypy .`, 'mypy');
+  if (/\[tool\.pyright/.test(py) || has('pyrightconfig.json')) add('typecheck', `${runner}pyright`, 'pyright');
+  if (/pytest/.test(py) || has('pytest.ini') || has('tests') || has('conftest.py')) add('test', `${runner}pytest`, 'pytest');
+}
+
+// Go
+if (has('go.mod')) {
+  add('build', 'go build ./...', 'go.mod');
+  add('lint', 'go vet ./...', 'go.mod');
+  if (has('.golangci.yml') || has('.golangci.yaml')) add('lint', 'golangci-lint run', '.golangci.yml');
+  add('test', 'go test ./...', 'go.mod');
+}
+
+// Rust
+if (has('Cargo.toml')) {
+  add('format', 'cargo fmt --check', 'Cargo.toml');
+  add('lint', 'cargo clippy --all-targets -- -D warnings', 'Cargo.toml');
+  add('test', 'cargo test', 'Cargo.toml');
+}
+
+// JVM
+if (has('gradlew')) {
+  add('build', './gradlew build -x test', 'gradlew');
+  add('test', './gradlew test', 'gradlew');
+} else if (has('pom.xml')) {
+  add('build', 'mvn -q -DskipTests package', 'pom.xml');
+  add('test', 'mvn -q test', 'pom.xml');
+}
+
+// .NET
+if (fs.readdirSync(root).some((f) => /\.(sln|csproj|fsproj)$/.test(f))) {
+  add('build', 'dotnet build', '.NET');
+  add('test', 'dotnet test', '.NET');
+}
+
+// Makefile targets
+const make = read('Makefile');
+for (const [kind, target] of [['build', 'build'], ['lint', 'lint'], ['typecheck', 'typecheck'], ['test', 'test']]) {
+  if (new RegExp(`^${target}:`, 'm').test(make)) add(kind, `make ${target}`, 'Makefile');
+}
+
+const order = ['build', 'format', 'lint', 'typecheck', 'test', 'test-integration'];
+checks.sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+
+const ci = has('.github/workflows') ? fs.readdirSync(path.join(root, '.github/workflows')).map((f) => `.github/workflows/${f}`) : [];
+console.log(JSON.stringify({ root, checks, ciFilesToReview: ci }, null, 2));
+if (!checks.length) process.exitCode = 3;

package/skills/video-editing/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: video-editing
+description: Editorial workflow for turning raw footage into a finished cut - logging clips and pulling selects, building a paper edit, rough cut then fine cut, pacing and J/L cuts, matching the rhythm of a reference edit, subtitles and captions in SRT or WebVTT, loudness to a delivery target, basic colour correction, and conforming from an edit decision list with FFmpeg or DaVinci Resolve's Python scripting API. Use when someone hands you interviews, B-roll or screen footage and wants a finished video, asks to tighten a rough cut, wants subtitles and levels fixed before delivery, or needs a timeline assembled or rendered from a script.
+license: MIT
+compatibility: Any Agent Skills host. Needs ffmpeg and ffprobe; Resolve scripting needs DaVinci Resolve running with scripting enabled and its API on PYTHONPATH. Transcription needs a speech-to-text tool the user approves.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ffmpeg, ffprobe"
+  kete-loom/owner: "Kete-org"
+---
+
+# Video editing
+
+Edit like an editor, not like a transcoder: decide what the piece says, choose the moments that say it, then make the cuts invisible. Keep every decision in an edit decision list (EDL) so the cut can be re-rendered, reviewed and changed. Single FFmpeg command recipes live in the `ffmpeg-media-processing` skill; this skill is about the edit.
+
+## 0. Brief first
+
+Before touching footage, get answers (ask the user for any that are missing):
+
+1. **Purpose and audience**: what should a viewer know or feel at the end?
+2. **Target length** and **delivery**: platform, aspect ratio (16:9, 9:16, 1:1), resolution, frame rate, captions burned in or as a sidecar file.
+3. **Reference**: a link or file whose pacing or look the user wants matched.
+4. **Must-haves and no-gos**: quotes that must stay, people or logos that must not appear, music licence.
+
+Never use music, footage or fonts the user has not confirmed they have rights to.
+
+## 1. Ingest and log
+
+1. Copy the camera originals to a read-only `source/` folder. Never edit or re-encode originals in place.
+2. Probe every clip: `ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,sample_rate,channels -show_entries format=duration -of json <clip>`. Flag mixed frame rates (for example 23.976 and 29.97) and variable frame rate phone footage now; they cause drift later.
+3. For VFR or long-GOP clips that will be cut a lot, make constant-frame-rate intermediates (`references/ffmpeg-edit-recipes.md`, "Proxies and intermediates").
+4. Transcribe speech (with the user's approval of the tool) to timestamped text. Spoken footage is edited from the transcript.
+5. Write a log, one row per clip: file, duration, content, usable ranges, quality notes (focus, noise, wind), best moments. Format in `references/edl-and-logging.md`.
+
+## 2. Selects and paper edit
+
+1. Mark selects: in and out timecodes of every moment worth keeping, with a one-line reason.
+2. Build a **paper edit**: the story order as a list of selects, before any rendering. Structure: hook (first 3 to 5 seconds), context, body in clear beats, payoff, call to action if any.
+3. Estimate running time from the list. If it is more than about 20% over target, cut whole beats now rather than trimming everything.
+4. **Stop and show the user the paper edit** for anything longer than a minute or with interview content. Changing a list is cheap; re-cutting is not.
+
+## 3. Rough cut
+
+Assemble the selects in order from the EDL with straight cuts and no polish. Render a low-resolution review copy with burned-in timecode (recipe in `references/ffmpeg-edit-recipes.md`) so feedback can cite exact times.
+
+Check: does it make sense with no music, titles or effects? If not, fix structure before moving on.
+
+## 4. Fine cut
+
+Work through these in order:
+
+1. **Trim**: remove ums, false starts, repeated points and dead air at clip heads and tails. Cut on the breath, not mid-word; leave 2 to 6 frames of room after the last syllable.
+2. **Pacing**: vary shot length; hold on what matters, move fast through what does not. Cut on action or a look; avoid jump cuts in an interview unless the style calls for them, otherwise cover them with B-roll.
+3. **J and L cuts**: let audio lead (J) or trail (L) the picture across a cut so speech flows.
+4. **B-roll**: cover edits and illustrate what is being said; never let B-roll contradict the words.
+5. **Match a reference**: measure the reference before imitating it (`references/ffmpeg-edit-recipes.md`, "Measure a reference"): average shot length, cuts per minute, text style, music level. Report the numbers next to yours.
+
+## 5. Sound
+
+1. Dialogue is king. Clean it first (noise reduction, high-pass around 80 Hz for voice), then set music under it.
+2. Duck music under speech by roughly 10 to 20 dB.
+3. Normalise the final mix to the delivery spec with a two-pass loudness measurement (`references/ffmpeg-edit-recipes.md`, "Loudness"). Common targets: EBU R128 broadcast -23 LUFS integrated; many streaming and social platforms normalise near -14 LUFS; keep true peak at or below -1 dBTP. Confirm the user's platform spec rather than assuming.
+4. Listen to every cut for pops; add short audio crossfades (a few frames) at each edit.
+
+## 6. Colour
+
+1. Correct before you grade: white balance, exposure, contrast, so shots of the same scene match.
+2. Then apply one look consistently. A LUT designed for a camera log profile goes on log footage only.
+3. Check skin tones and that nothing is clipped. Do not grade on an uncalibrated laptop screen and call it final; tell the user.
+
+## 7. Captions and subtitles
+
+1. Start from the transcript, corrected by hand against the final cut, not the raw footage.
+2. Write SRT or WebVTT timed to the final timeline. Rules of thumb (check the platform's style guide): at most 2 lines, about 42 characters per line, reading speed around 17 to 20 characters per second, minimum about 1 second on screen, break lines at phrase boundaries.
+3. Sidecar files keep captions accessible and editable; burn in only when the platform needs it (many social feeds autoplay muted). See `references/ffmpeg-edit-recipes.md`, "Subtitles".
+4. Re-time captions after every picture change.
+
+## 8. Conform and render
+
+- **FFmpeg path**: generate the render from the EDL (trim and concat, then the audio chain, then subtitles). Recipes in `references/ffmpeg-edit-recipes.md`.
+- **DaVinci Resolve path**: build the timeline, import an EDL, FCPXML or AAF, set render settings and queue the job from Python. API calls in `references/resolve-scripting.md`.
+- Render a master (high bitrate or mezzanine codec) and derive delivery files from it; never re-encode a delivery file to make another.
+
+## 9. QC before delivery
+
+Watch the whole render once, start to finish, then check:
+
+- [ ] Duration, resolution, frame rate and aspect ratio match the brief (probe the file).
+- [ ] No black frames, flash frames or frozen frames at cut points (`blackdetect`, `freezedetect` in the recipes).
+- [ ] Audio in sync at the start, middle and end; loudness measured on the final file.
+- [ ] Captions match the words and timing; names spelled correctly.
+- [ ] Nothing from the no-go list appears.
+
+## Never
+
+- Never alter source files or delete footage the user has not approved deleting.
+- Never invent quotes or re-order an interviewee's words so the meaning changes. Flag any edit that compresses what someone said.
+- Never deliver without watching the final render.
+
+## Report back
+
+```
+Cut: <title> v<n>   Length: mm:ss (target mm:ss)   Format: WxH @ fps, codec
+EDL: <path>   Master: <path>   Deliverables: <paths>
+Structure: hook / beats / payoff (one line each)
+Audio: integrated LUFS, true peak     Captions: <file or burned in>
+Changes since last version: ...
+Open questions / needs a human: grading on a calibrated display, legal clearance, ...
+```

package/skills/video-editing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "I have three hours of interview footage and B-roll, cut it into a 4-minute documentary short",
+    "Tighten this rough cut: remove the ums, fix the pacing and add J and L cuts between speakers",
+    "Make my edit feel like this reference video, same rhythm of cuts and same music level",
+    "Build a DaVinci Resolve timeline from my selects list with a Python script and queue the render",
+    "Before we deliver, fix the audio levels to -14 LUFS, colour match the two cameras and add subtitles to the final cut"
+  ],
+  "should_not_trigger": [
+    "Convert this MKV to an MP4 that plays on an iPhone",
+    "Record a walkthrough video of our web app's onboarding flow using Playwright",
+    "Animate a title card sequence in React and render it to MP4",
+    "Generate a 10-second product clip from a text prompt with a video model",
+    "Repurpose our webinar recording into a LinkedIn post and a thread"
+  ]
+}

package/skills/video-editing/references/edl-and-logging.md

@@ -0,0 +1,44 @@
+# Logs, selects and EDLs
+
+## Clip log (CSV)
+
+```
+file,duration,content,usable_in,usable_out,quality,best_moment,notes
+A001_C003.mov,00:04:12,Interview Ana wide,00:00:08,00:04:02,good,"00:01:15 'we almost quit'",slight wind at 3:40
+```
+
+## Working EDL (JSON, the source of truth for the FFmpeg path)
+
+Keep times as seconds with three decimals, or as frames at the project rate. One entry per event, in timeline order.
+
+```json
+{
+  "fps": 25,
+  "width": 1920, "height": 1080,
+  "events": [
+    { "id": 1, "src": "source/A001_C003.mov", "in": 75.20, "out": 82.04, "track": "V1+A1", "note": "hook quote" },
+    { "id": 2, "src": "source/B012.mov", "in": 3.00, "out": 6.50, "track": "V1", "audio_from": 1, "note": "B-roll over quote" }
+  ],
+  "music": [{ "src": "music/bed.wav", "start": 0.0, "gain_db": -18 }],
+  "captions": "captions/final.srt"
+}
+```
+
+Rules:
+- `in`/`out` refer to the source clip; the timeline position is the running sum of durations.
+- Snap cut points to frame boundaries at the project frame rate (`round(t * fps) / fps`).
+- Bump a version number on every change and keep old EDLs.
+
+## CMX 3600 EDL (for handing to an NLE)
+
+```
+TITLE: MY_CUT_V3
+FCM: NON-DROP FRAME
+
+001  A001C003 V     C        00:01:15:05 00:01:22:01 01:00:00:00 01:00:06:21
+002  A001C003 A     C        00:01:15:05 00:01:22:01 01:00:00:00 01:00:06:21
+```
+
+Fields: event number, reel name (max 8 characters in strict CMX 3600), track (V, A, A2, B for both), transition (C = cut, D = dissolve with duration), source in, source out, record in, record out. CMX 3600 carries one video track; use FCPXML or AAF for multitrack timelines, titles and effects.
+
+Timecode: `HH:MM:SS:FF`. Use drop-frame (`;` before frames, `FCM: DROP FRAME`) only for 29.97 or 59.94 material that is delivered drop-frame.

package/skills/video-editing/references/ffmpeg-edit-recipes.md

@@ -0,0 +1,92 @@
+# FFmpeg recipes for editing
+
+Pass arguments as arrays from code, never via shell strings built from user input.
+
+## Proxies and intermediates
+
+Constant frame rate, all-intra, easy to cut:
+
+```bash
+ffmpeg -i in.mp4 -vf "fps=25,scale=-2:1080" -c:v prores_ks -profile:v 1 -c:a pcm_s16le -ar 48000 inter.mov
+# smaller review proxy
+ffmpeg -i in.mp4 -vf "fps=25,scale=-2:540" -c:v libx264 -g 1 -crf 23 -c:a aac proxy.mp4
+```
+
+## Trim one event frame-accurately
+
+Re-encode when cutting long-GOP sources; `-c copy` cuts on keyframes only.
+
+```bash
+ffmpeg -ss 75.20 -i source/A001_C003.mov -t 6.84 -c:v libx264 -crf 16 -preset slow -c:a pcm_s16le -ar 48000 seg001.mov
+```
+
+## Join events
+
+After all segments share codec, resolution, frame rate and audio layout:
+
+```bash
+printf "file '%s'\n" seg001.mov seg002.mov > list.txt
+ffmpeg -f concat -safe 0 -i list.txt -c copy assembled.mov
+```
+
+For short cross-dissolves, use `xfade` (video) and `acrossfade` (audio) in a filter graph instead of the concat demuxer.
+
+## Burned-in timecode for review copies
+
+```bash
+ffmpeg -i assembled.mov -vf "drawtext=timecode='00\:00\:00\:00':rate=25:fontsize=36:fontcolor=white:box=1:boxcolor=black@0.5:x=20:y=h-th-20" -c:v libx264 -crf 26 -c:a aac review.mp4
+```
+
+Some builds need `fontfile=/path/to/font.ttf` in `drawtext`.
+
+## Measure a reference
+
+Shot boundaries (scene score above 0.3 is a common starting threshold; tune per footage):
+
+```bash
+ffmpeg -i reference.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null - 2>&1 | grep -o "pts_time:[0-9.]*"
+```
+
+Cuts per minute = number of boundaries / duration in minutes. Average shot length = duration / (boundaries + 1). Measure loudness of the reference the same way as your mix (below).
+
+## Loudness (two-pass loudnorm)
+
+```bash
+# pass 1: measure
+ffmpeg -i mix.wav -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null -
+# pass 2: apply with the measured values
+ffmpeg -i mix.wav -af "loudnorm=I=-14:TP=-1:LRA=11:measured_I=<i>:measured_TP=<tp>:measured_LRA=<lra>:measured_thresh=<thr>:offset=<off>:linear=true" -ar 48000 mix_norm.wav
+# verify on the final file
+ffmpeg -i final.mp4 -af ebur128=peak=true -f null -
+```
+
+Change `I` to the delivery target (for example -23 for EBU R128).
+
+## Ducking music under dialogue
+
+```bash
+ffmpeg -i dialogue.wav -i music.wav -filter_complex "[1:a][0:a]sidechaincompress=threshold=0.05:ratio=8:attack=20:release=400[duck];[0:a][duck]amix=inputs=2:duration=first:normalize=0[out]" -map "[out]" mix.wav
+```
+
+## Subtitles
+
+```bash
+# soft subtitles in MP4 (mov_text) or MKV (srt)
+ffmpeg -i final.mp4 -i captions.srt -map 0 -map 1 -c copy -c:s mov_text -metadata:s:s:0 language=eng final_subs.mp4
+# burn in
+ffmpeg -i final.mp4 -vf "subtitles=captions.srt:force_style='FontSize=24,Outline=2'" -c:a copy final_burned.mp4
+```
+
+## QC detectors
+
+```bash
+ffmpeg -i final.mp4 -vf "blackdetect=d=0.1:pix_th=0.10" -an -f null - 2>&1 | grep blackdetect
+ffmpeg -i final.mp4 -vf "freezedetect=n=0.003:d=0.5" -an -f null - 2>&1 | grep freeze
+```
+
+## Basic colour correction
+
+```bash
+ffmpeg -i in.mov -vf "eq=contrast=1.05:brightness=0.02:saturation=1.1,colortemperature=temperature=5600" out.mov
+ffmpeg -i log.mov -vf "lut3d=camera_log_to_rec709.cube" graded.mov
+```

package/skills/video-editing/references/resolve-scripting.md

@@ -0,0 +1,53 @@
+# DaVinci Resolve scripting (Python)
+
+The authoritative reference is the README shipped with Resolve (Help > Documentation > Developer, `Scripting/README.txt`). Method names and supported export formats change between versions; check that file for the installed version before relying on a call below.
+
+## Setup
+
+- Resolve must be running. Scripting access (local or network) is set in Preferences > System > General > External scripting using.
+- External scripts need the environment the README describes, typically `RESOLVE_SCRIPT_API`, `RESOLVE_SCRIPT_LIB` and `PYTHONPATH` pointing at the bundled `Modules` folder.
+- Which features need the paid Studio edition varies by version; check the README and tell the user if a call fails for that reason.
+
+## Common calls
+
+```python
+import time
+import DaVinciResolveScript as dvr
+
+resolve = dvr.scriptapp("Resolve")
+pm = resolve.GetProjectManager()
+project = pm.GetCurrentProject() or pm.CreateProject("my_cut")
+media_pool = project.GetMediaPool()
+
+clips = media_pool.ImportMedia(["/abs/source/A001_C003.mov", "/abs/source/B012.mov"])
+timeline = media_pool.CreateEmptyTimeline("my_cut_v1")
+project.SetCurrentTimeline(timeline)
+
+# Append sub-clips by source frame range
+media_pool.AppendToTimeline([
+    {"mediaPoolItem": clips[0], "startFrame": 1880, "endFrame": 2051},
+    {"mediaPoolItem": clips[1], "startFrame": 75, "endFrame": 162},
+])
+
+# Or import a whole timeline from an EDL / FCPXML / AAF
+media_pool.ImportTimelineFromFile("/abs/edl/my_cut_v3.fcpxml")
+
+# Export the timeline for review or hand-off
+timeline.Export("/abs/out/my_cut_v3.edl", resolve.EXPORT_EDL, resolve.EXPORT_NONE)
+
+# Render
+resolve.OpenPage("deliver")
+project.LoadRenderPreset("H.264 Master")  # a preset that exists on this machine
+project.SetRenderSettings({"TargetDir": "/abs/out", "CustomName": "my_cut_v3"})
+job_id = project.AddRenderJob()
+project.StartRendering(job_id)
+while project.IsRenderingInProgress():
+    time.sleep(2)
+```
+
+## Rules
+
+- Check every return value: most calls return `None` or `False` on failure without raising.
+- Use absolute paths.
+- Never delete media pool items, timelines or projects the script did not create.
+- Save the project (`pm.SaveProject()`) before and after a scripted change.

package/skills/vite-patterns/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: vite-patterns
+description: Configuring and debugging Vite builds and dev servers, covering vite.config with defineConfig and loadEnv, VITE_ env variables and modes, path aliases, plugin ordering and writing small plugins, library mode with package exports, SSR entry builds, base path and build output, and fixing breakage when moving from webpack or Create React App or across Vite majors (Rollup to Rolldown). Use when editing vite.config, env variables are undefined in the browser, an alias or import fails only in build, publishing a library with Vite, or upgrading Vite.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js and the project's package manager. Option names changed between Vite majors; check the installed version (npx vite --version) and vite.dev/guide/migration.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Vite patterns
+
+Vite serves source over native ESM in dev and bundles for production. Most bugs come from the gap between those two modes, from env variables, or from options renamed between majors.
+
+## First, look at the project
+
+1. Read `package.json` for the `vite` major and framework plugin (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, `@sveltejs/vite-plugin-svelte`), and whether a meta-framework (Nuxt, SvelteKit, Astro, Remix/React Router) owns the config.
+2. Read `vite.config.*` and `tsconfig.json`.
+3. If a meta-framework wraps Vite, change Vite settings through that framework's config key (for example `vite:` in `nuxt.config`), not a separate `vite.config`.
+
+**Version matters.** Vite 8 builds with Rolldown and transforms with Oxc: `build.rollupOptions` became `build.rolldownOptions`, top-level `esbuild` options became `oxc`, and `optimizeDeps.esbuildOptions` became `optimizeDeps.rolldownOptions`. The old names are deprecated but still accepted. Use the names that match the installed major.
+
+## Config
+
+```ts
+import { defineConfig, loadEnv } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig(({ command, mode }) => {
+  const env = loadEnv(mode, process.cwd(), ''); // '' = load all vars, for config use only
+  return {
+    plugins: [react()],
+    server: { port: 5173, proxy: { '/api': { target: env.API_URL, changeOrigin: true } } },
+    build: { sourcemap: mode !== 'production' ? true : 'hidden' },
+  };
+});
+```
+
+- `import.meta.env` is **not** available inside `vite.config`; env files load after the config runs. Use `loadEnv(mode, root, prefixes)` there.
+- Use `server.proxy` in dev to avoid CORS instead of adding CORS headers to the backend for localhost.
+
+## Env variables and modes
+
+- Only variables starting with `VITE_` (or a custom `envPrefix`) reach client code, through `import.meta.env.VITE_*`. All values are strings.
+- Files: `.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local`; mode-specific files win, and variables already set in the shell win over all files. Restart the dev server after editing them.
+- Built-ins: `import.meta.env.MODE`, `BASE_URL`, `PROD`, `DEV`, `SSR`.
+- `mode` and `NODE_ENV` are different: `vite build --mode staging` still builds with `NODE_ENV=production` and loads `.env.staging`.
+- **Everything with the client prefix is embedded in the shipped JS.** Never put secrets in `VITE_*`. Keep `*.local` in `.gitignore`.
+- Type them in `src/vite-env.d.ts` with an `interface ImportMetaEnv { readonly VITE_API_URL: string }`.
+- `process.env.X` in client code is not replaced; use `import.meta.env` or `define`.
+- Bun auto-loads `.env` into `process.env`, which can mask Vite's own loading; run Vite under Node or disable Bun's env loading.
+
+## Aliases
+
+- Declare once and keep TypeScript in sync. Either set `resolve.alias` (`{ '@': fileURLToPath(new URL('./src', import.meta.url)) }`) and mirror it in `tsconfig` `paths`, or on Vite 8 enable `resolve.tsconfigPaths` to read `paths` from `tsconfig` directly (the `vite-tsconfig-paths` plugin on older majors).
+- Tests (Vitest) reuse `vite.config`, so aliases defined there work in tests too.
+
+## Plugins
+
+- Order: framework plugin first, then others. A plugin can set `enforce: 'pre' | 'post'` and `apply: 'serve' | 'build'`.
+- A small project plugin is an object with `name` plus hooks (`config`, `configResolved`, `resolveId`, `load`, `transform`, `configureServer`, `transformIndexHtml`). Return `null` from `resolveId`/`load`/`transform` for ids you do not handle.
+- Prefer an existing official or widely used plugin over a custom one. Check that a plugin supports the installed Vite major before adding it.
+
+## Library mode
+
+```ts
+build: {
+  lib: { entry: 'src/index.ts', name: 'MyLib', fileName: 'my-lib', formats: ['es', 'cjs'] },
+  rolldownOptions: { external: ['react', 'react-dom', 'react/jsx-runtime'] }, // rollupOptions before Vite 8
+}
+```
+
+- Externalise every `peerDependency` and usually every `dependency`; bundling React into a component library breaks hooks.
+- `package.json`: `"type": "module"`, `"files": ["dist"]`, and an `exports` map with `types`, `import` and `require` conditions pointing at real files. Add `"./style.css"` if CSS is emitted.
+- Vite does not emit `.d.ts`: run `tsc --emitDeclarationOnly` or a declarations plugin.
+- Verify with `npm pack --dry-run` and by importing the packed tarball in a scratch project.
+
+## SSR
+
+- Prefer a framework (Nuxt, SvelteKit, Astro, React Router) over hand-rolled SSR. For a custom server: create Vite in middleware mode (`createServer({ server: { middlewareMode: true }, appType: 'custom' })`), mount `vite.middlewares`, and load the entry with `vite.ssrLoadModule('/src/entry-server.ts')` in dev.
+- Production: build twice, the client (`vite build --outDir dist/client`) and the server entry (`vite build --ssr src/entry-server.ts --outDir dist/server`).
+- Dependencies that ship untranspiled code or CSS imports may need `ssr.noExternal: ['pkg']`.
+- Guard browser globals (`window`, `document`) behind `import.meta.env.SSR` or lifecycle hooks.
+
+## Build output
+
+- `base`: set it when the app is served from a sub-path (`base: '/app/'`), and use `import.meta.env.BASE_URL` when building URLs at runtime.
+- Files in `public/` are copied as-is and referenced by absolute path; imported assets get hashed names. Do not import from `public/`.
+- `build.target` defaults to a Baseline-widely-available browser set; Vite adds no polyfills. Use `@vitejs/plugin-legacy` only if old browsers are a real requirement.
+- Check bundle size with `vite build` output, and split heavy routes with dynamic `import()`. On Vite 8 the object form of `manualChunks` is no longer supported and the function form is deprecated; use Rolldown's `codeSplitting` option instead.
+- `vite preview` serves `dist` locally to test the production build; it is not a production server.
+
+## Common migration issues
+
+| Symptom | Fix |
+|---|---|
+| `process is not defined` after leaving webpack/CRA | Replace `process.env.REACT_APP_*` with `import.meta.env.VITE_*`; `define` only for third-party code |
+| `require is not defined` | Convert to `import`; Vite source is ESM |
+| `index.html` not found / blank page | `index.html` lives at the project root with `<script type="module" src="/src/main.tsx">` |
+| JSX in `.js` files fails | Rename to `.jsx`/`.tsx` |
+| Works in dev, broken in build | Case-sensitive import paths, CJS default-import interop, or a dynamic import with a variable path; run `vite build && vite preview` to reproduce |
+| Default import from a CJS package changed after a Vite major | Fix the import; `legacy.inconsistentCjsInterop` only as a temporary bridge |
+| Dependency pre-bundling stale | Delete `node_modules/.vite` or run with `--force` |
+
+## Never
+
+- Put secrets in `VITE_*` variables or `define`.
+- Bundle peer dependencies into a library build.
+- Copy a config snippet written for a different Vite major without checking option names.
+- Serve production traffic with `vite` or `vite preview`.
+
+## Before you finish
+
+Run `vite build` (and `vite preview` for app changes) plus the project's type-check and tests. Report the config keys changed, any new plugin, env variables the user must set, and the build result.

package/skills/vite-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "import.meta.env.API_URL is undefined in the browser in my Vite app",
+    "Set up Vite library mode so our component package ships ESM and CJS without bundling React",
+    "We're moving off Create React App to Vite and get 'process is not defined'",
+    "The @ alias resolves in dev but the vite build fails to find the module",
+    "Upgrade our vite.config from rollupOptions to the new Vite 8 options"
+  ],
+  "should_not_trigger": [
+    "Our React components re-render too often, how do I memoize them properly",
+    "Configure nuxt.config route rules for prerendering the marketing pages",
+    "Migrate our Jest tests to bun test",
+    "Reduce our Largest Contentful Paint on the landing page",
+    "Add helmet and CORS to the Fastify API server"
+  ]
+}