lecodes-assets 0.2.1 → 2.4.10

package/src/cli.ts

@@ -1,1039 +1,24 @@
-#!/usr/bin/env node
-// lecodes-assets — the LeCodes asset pipeline CLI (also reachable as `lecodes assets …`).
-//
-//   convert <model.fbx|.glb|.uasset|.bvh> [--clips a.fbx b.uasset …] [--clip-names n1 n2 …] [--drop-model-clips]
-//           [--rename from=to …] [-o out.glb] [--fix] [--ktx2 | --ktx2-hq] [--max-size N] [--target N]
-//           [--fix-scale | --scale N | --scale-to M]
-//   retarget <target.glb> --from <donor.fbx|.glb|.uasset|.bvh> --map <map.json> [-o out.glb] [--skeletons]
-//   avatar  <model.fbx|.glb|.uasset> [--meta model.fbx.meta] [-o model.avatar.json]
-//   mirror  <model.glb> [--clips a b …] [--suffix _M] [--axis x|y|z] [-o out.glb]
-//   bvh     <model.glb> --clip <name> [--fps 30] -o out.bvh     one clip as a Kimodo-style BVH
-//   unpack  <pkg.unitypackage> [-o dir] [--only regex …] [--list]
-//   sky     <env.exr|.hdr> [-o dir] [--size N] [--ibl-size N] [--name n] [--ibl-name n] [--ibl-only]
-//   terrain-pack <layer|dir> … [-o dir] [--normals n0 n1 …] [--names a b …] [--size N] [--png] [--flip-y]
-//   probe   <file.fbx|.glb|.uasset>
-//   unreal  ls <dir> [--all]
-//   doctor  <input.glb | dir | "*.glb"> [--fix] [--ktx2] [--ktx2-hq] [--fix-metallic] [--fix-emissive] [--unlit] [-o out] [--dump [dir]] [--target N] [--max-size N]
-//           [--fix-scale | --scale N | --scale-to M]
-
-import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "node:fs"
-import { buildSky, formatSkyReport } from "./sky"
-import { basename, dirname, extname, join, resolve } from "node:path"
-
-const USAGE = `lecodes-assets — FBX → GLB converter + GLB doctor (docs/animation-plan.md §2.9)
-
-  convert <model.fbx|.glb|.uasset> [opts]   FBX, an existing GLB, or an UNREAL asset → LeCodes-ready GLB
-      --clips a.fbx b.uasset …              merge these files' animations into the model, bound by BONE NAME
-                                            (FBX or Unreal AnimSequence; globs and folders expand)
-      --clip-names n1 n2 …                  names for --clips (default: stack name, or the file name when generic)
-      --drop-model-clips                    drop the model file's own clips (e.g. Mixamo's 1-frame T-pose)
-      --rename clipBone=modelBone …         bone name overrides for clip binding
-      -o out.glb                            output (default: <model>.glb next to the input)
-      --skeleton <SK.uasset>                (Unreal) the skeleton a clip was authored on — by default it is
-                                            found in the pack by the object path the clip carries
-      --content-root <dir>                  (Unreal) the pack's Content folder, if the search cannot find it
-      --lod-level N                         (Unreal) which mesh LOD to read (default 0)
-      --no-textures                         (Unreal) keep the grey material slots instead of pulling the
-                                            pack's textures (they need an Oodle library — see the README)
-      --no-normal-flip                      (Unreal) keep normal maps DirectX-style (UE authors them
-                                            green-down; glTF wants green-up, so they are flipped)
-      --fix                                 run the doctor passes (bone cap, texture normalize) before writing
-      --ktx2 | --ktx2-hq | --ktx2-uastc     textures → KTX2 (needs KTX-Software toktx). Default puts only
-                                            colour on ETC1S; -hq also keeps NORMALS on UASTC; -uastc puts
-                                            EVERYTHING on UASTC — for HERO assets (first-person weapon,
-                                            gloves) where ETC1S blocking is visible at 30 cm. ~8x larger.
-      --max-size N  --target N              texture size cap (2048) / bone cap (256)
-      --fix-scale                           bake an auto unit fix (cm/mm/inch/0.01-armature → metres)
-      --scale N | --scale-to M              bake an explicit factor / make the largest dimension M metres
-      --fix-emissive | --unlit              drop a self-lit emissive / go flat (see doctor)
-      --lightmap-uv                         add a lightmap UV set (see doctor)
-      --unity-mats <dir> | --no-unity       Unity .mat files are read for the REAL textures (metallic/
-                                            roughness/ORM/emission/alpha mode) when they sit next to the
-                                            FBX — point elsewhere, or switch it off
-      --unity-index <unity-index.txt>       GUID → path table (default: found above the FBX, else .meta files)
-      --merge-skins b.fbx c.glb …           modular characters: move these files' SKINNED meshes onto the
-                                            model's skeleton (joints matched by name), drop their skeleton copies
-      --list-nodes [depth]                  print the scene's nodes (multi-variant prop files) and exit
-      --keep <node> …                       keep only these nodes (+ their subtrees), re-origin the result
-                                            (footprint centre at X/Z = 0, lowest point at Y = 0); --no-ground
-                                            keeps the file's own placement
-      --split [dir]                         one GLB per top-level node, each re-origined (default: <out>/)
-  mirror <model.glb> [--clips a b …] [--suffix _M] [--axis x|y|z] [-o out.glb]
-  marks   <model.glb> [--stairs <regex>|all|none] [--platforms <regex>|all|none] [--fps N] [--clips a b …] [-o out.glb]
-                                            measure every clip's FOOT MARKS (touch spans, still windows, lift-offs,
-                                            the staircase of a stair clip) on the model's own skeleton and write
-                                            them into the GLB (extras.lecodes.contacts) — for packs that are not
-                                            retargeted; retarget writes the same block itself
-                                            add MIRRORED copies of clips (left ↔ right): a stop that brakes on
-                                            the left foot becomes one that brakes on the right. World-space
-                                            deltas from the bind reflected across the sagittal plane, bones
-                                            paired by name (Left/Right, L_/R_, .L/.R) and checked against
-                                            the bind geometry. Needs the skin (the bind pose) in the file.
-  unpack <pkg.unitypackage> [-o dir] [--only re …] [--list]
-                                            stream a .unitypackage: writes <dir>/unity-index.txt (GUID → path)
-                                            and the assets (+ .meta) matching --only (default: all)
-  retarget <target.glb> --from <donor.fbx|.glb|.uasset> --map <map.json> [options]
-                                            drive one rig with ANOTHER rig's clips (different bone
-                                            names, chain lengths and axis conventions are all fine)
-      --map map.json                        { "root": "Hips", "bones": { targetBone: donorBone },
-                                              "align": { bone: "keep" | "direction" | [ refBones ] },
-                                              "legs": [ footBones ] }   (align/legs optional)
-      --skeletons                           print both bone lists and exit (to write that map)
-      --auto-map [out.json] | --map auto    derive the map from the two skeletons' SHAPE — write it, or use it
-                                            directly. Quadrupeds: spine/neck/head/tail/legs/ears/jaw chains.
-                                            Humanoids: both rigs' AVATARS (see \`avatar\`) joined on the canon
-      --avatar <a.avatar.json|model.meta>   the target's avatar instead of deriving it (a Unity .meta works)
-      --donor-avatar <…>                    the donor's
-      --donor-rig <model.fbx|.glb|.uasset>  the rig a skeleton-only clip file (mocap packs: nodes + curves,
-                                            no mesh) was animated on — its clips bind to it by bone name
-      --clips a b …                         only these donor clips        --keep-clips  keep the target's own
-      --align none|bone-direction           posture alignment (default bone-direction)
-      --ik none|legs|hands                  foot placement against the ground (default legs); hands = the
-                                            hands as effectors too (clips where they meet or hold)
-      --heading-end DEG                     the baked heading curve must END here (a stop that turns: its idle faces the turn)
-      --root-motion auto|hips|root|none     where the travel lands: a root above the hips takes the horizontal
-                                            travel, the hips the bob (auto/root); all on the hips; none = in place
-      --no-plant                            no foot planting (each foot is otherwise LOCKED through its still windows)
-      --foot-stance target|donor            the horizontal stance a planted foot keeps: the target's own foot-under-hip
-                                            offset + the donor's departure from its bind (default), or the donor's offset
-                                            whole — a humanoid bound legs-apart keeps its step width
-      --stairs <regex>|all|none             donor clips to fit a STAIRCASE to (default: names containing "stair")
-      --platforms <regex>|all|none          donor clips with a PLATFORM: two levels, the floor and the top (default
-                                            "platform"); a foot slow at any other height (the wall) is no plant
-      --twist N|off                         twist helpers' share of their limb's axial turn (default 0.5)
-      --donor-ref bind|auto|<clip>          pose the donor's motion is measured from (auto = mean of its idle/walk)
-      --fps N  --root-scale N  --prefix s   sampling rate / root-motion scale / clip name prefix
-      --epsilon M  --epsilon-deg D          key-reduction tolerances (default 1e-4 m / 0.2°; hips + legs 0.01°)
-      --body-clearance M                    a joint the donor has on the floor (a roll's back) keeps this much
-                                            over the target's ground beyond the donor's height (default 0.05)
-      --clip-names n1 n2 …                  rename the produced clips, positionally
-      --anim a.anim b.uasset …              clip assets to use as the donor's clips: Unity AnimationClips
-                                            (packs shipping an empty FBX rig + .anim files) or Unreal
-                                            AnimSequences (each on its own skeleton, bound by bone name)
-  avatar <model.fbx|.glb|.uasset> [--meta model.fbx.meta] [-o model.avatar.json]
-                                            a humanoid rig's AVATAR: its bones named in the Unity/VRM canon
-                                            (Hips, Spine…, LeftUpperArm…, Left Thumb Proximal…), read off the
-                                            skeleton's shape — hips = the joint two ground-reaching chains hang
-                                            from, hands = the lateral joints fanning into fingers, head = the
-                                            last branch above the arms; twist/roll helpers recorded, not mapped.
-                                            --meta checks the result against Unity's own humanoid map (and
-                                            imports it verbatim when you trust it more: -o with --meta writes
-                                            Unity's). The file is what \`retarget --avatar\` reads
-  sky <env.exr|.hdr>                        equirectangular HDR → the TWO cubemaps a scene needs
-      -o dir                                where they land (default: beside the input)
-      --size N                              edge of the DRAWN sky cubemap (default 512)
-      --ibl-size N                          edge of the lighting probe (default 256 — it is only ever
-                                            sampled as low-frequency light, so it stays small)
-      --name n  --ibl-name n                names without extension (default sky / ibl)
-      --ibl-only                            lighting probe only, no drawn sky
-                                            Writes sky.ktx (sharp — use it for \`skybox: { texture }\`)
-                                            and ibl.ktx (prefiltered + SH — lights the scene). They are
-                                            NOT interchangeable: the IBL is blurred by design, so
-                                            drawing it as the sky looks soft. Also reports WHERE THE
-                                            SUN IS in the environment, so the scene's directional light
-                                            can be aimed to match instead of by eye.
-                                            Needs filament's cmgen (LECODES_CMGEN / ~/.lecodes/cmgen).
-
-  terrain-pack <layer> [<layer> …]          a terrain's splat layers (≤ 4) → <name>.ktx2 per layer + the PACKED
-                                            normal maps normals01.ktx2 / normals23.ktx2 (layer XY pairs in
-                                            RG/BA — terrain.mat has nine samplers, so normals ship two per
-                                            texture). A layer = an albedo file (its normal guessed from the
-                                            name, or --normals) or a FOLDER holding *Albedo* + *Normal*
-                                            (Unity terrain packs). Prints the Terrain.create fragment
-      -o dir                                where they land (default: ./terrain)
-      --normals n0 n1 …                     normal map per layer, positionally ("-" = none)
-      --names a b …                         layer names → file names (default: from the inputs)
-      --size N                              output edge (1024)          --quality N   UASTC quality 0–4 (1)
-      --png                                 PNGs instead of KTX2 (no toktx needed)
-      --flip-y                              DirectX-style normal maps (green inverted)
-
-  probe <file.fbx|.glb|.uasset>             skeleton, clips (+ per-clip root motion / first-frame-vs-rest),
-                                            meshes, materials, textures, bind sanity, world size, duplicate names
-      --filmstrip [out.png]                 (GLB) CPU-skinned PNG strip of every clip — the fastest "does it play
-                                            upright" check, no GPU; --clip <name> for one, --frames N (6),
-                                            --view side|front|top|threequarter|lowfront, --bones, --cell px
-  scene <map.unity> [-o level.json]         Unity scene → level JSON: every placed prefab / mesh object with its
-                                            world TRS in LeCodes' frame + the prefab table (FBX + --keep node guess)
-      --filter re  --group name  --region x0,z0,x1,z1   subset by prefab path/name, scene group, Unity X/Z rect
-      --handedness x|z|none                 how Unity's left-handed frame is undone (default x: −x, (x,−y,−z,w))
-      --include-inactive  --index <unity-index.txt>
-  unreal tex <T_x.uasset> [-o out.png]      the SOURCE image out of a texture asset (Oodle-compressed —
-                                            see the README); --raw writes it exactly as stored,
-                                            --max-size N downscales, --flip-green for a normal map
-  unreal ls <dir> [--all]                   what an UNREAL pack holds: every .uasset by class, grouped by the
-                                            skeleton it belongs to, with the reason for anything unreadable
-                                            (a UE4 package, a mesh with no import data, a clip
-                                            whose rig is elsewhere). Reads only the headers — a 800-asset
-                                            pack lists in a second. convert/probe/retarget take
-                                            .uasset files directly (uncooked UE 5.0-5.7 editor assets:
-                                            SkeletalMesh, Skeleton, AnimSequence)
-
-  doctor <in.glb | dir | "*.glb"> [--fix] [--ktx2] [--ktx2-hq] [--fix-metallic] [-o out] [--dump [dir]] [--target N] [--max-size N]
-                                            analyze / fix a GLB against creator-gl limits (the old glb-reduce)
-         [--fix-scale | --scale N | --scale-to M]
-                                            scale normalization — always REPORTED, applied only with a flag
-         [--fix-emissive]                   drop a self-lit emissive (emissive = base colour → ~2x too bright)
-         [--unlit]                          flat base colour, no lighting (KHR_materials_unlit) — for stylised assets
-         [--lightmap-uv]                    add a lightmap UV set (TEXCOORD_1, xatlas) — what \`lecodes lightmap bake\`
-                                            samples; skinned meshes are skipped. --lightmap-padding N (4),
-                                            --lightmap-iterations N (1, more = better charts, slower)
-         [--lod 0.5,0.2] [--lod-bones]     add mesh LOD levels (<name>_LOD1... siblings at these triangle
-                                            ratios, same skin; >= 2000-tri meshes only) - creator-gl shows one
-                                            by screen size (docs/lod-plan.md); --lod-bones folds fingers /
-                                            toes / twists onto their parents in the last level's skin`
-
-type Parsed = { positionals: string[], flags: Set<string>, values: Map<string, string[]> }
-const MULTI = new Set([ "--clips", "--clip-names", "--rename", "--anim", "--only", "--keep", "--merge-skins", "--normals", "--names" ])
-const SINGLE = new Set([ "-o", "--clip", "--max-size", "--target", "--dump", "--scale", "--scale-to", "--from", "--map", "--auto-map", "--align", "--ik", "--donor-ref", "--stairs", "--platforms", "--body-clearance", "--epsilon", "--epsilon-deg", "--fps", "--root-scale", "--prefix", "--unity-mats", "--unity-index",
-  "--skeleton", "--content-root", "--lod-level",
-  "--avatar", "--donor-avatar", "--meta", "--root-motion", "--twist", "--donor-rig", "--heading-end", "--foot-stance",
-  "--split", "--list-nodes", "--filmstrip", "--frames", "--view", "--clip", "--cell", "--filter", "--group", "--region", "--handedness", "--index",
-  "--size", "--ibl-size", "--name", "--ibl-name", "--lightmap-padding", "--lightmap-iterations", "--quality", "--lod", "--suffix", "--axis" ])
-
-// `--region -10,0,50,60` / `--scale -1`: "-" + digit is a negative number, not the next flag.
-const isValue = (s: string): boolean => !s.startsWith("-") || /^-(\d|\.\d)/.test(s)
-
-const parse = (argv: string[]): Parsed => {
-  const positionals: string[] = []
-  const flags = new Set<string>()
-  const values = new Map<string, string[]>()
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (MULTI.has(a)) {
-      const list: string[] = []
-      while (i + 1 < argv.length && isValue(argv[i + 1])) list.push(argv[++i])
-      values.set(a, [ ...(values.get(a) ?? []), ...list ])
-    } else if (SINGLE.has(a)) {
-      if (i + 1 < argv.length && isValue(argv[i + 1])) values.set(a, [ argv[++i] ])
-      else values.set(a, [])
-    } else if (a.startsWith("-") && !isValue(a)) flags.add(a)
-    else positionals.push(a)
-  }
-  return { positionals, flags, values }
-}
-
-const log = (s: string): void => console.log(s)
-
-const cmdMarks = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { makeIO, writeGlb } = await import("./fbx/convert")
-  const { writeMarks } = await import("./retarget/writeMarks")
-  const { stairsMatcher, describeMarks } = await import("./retarget/marks")
-  const t0 = performance.now()
-  const doc = await makeIO().read(input)
-  const rows = writeMarks(doc, { stairs: stairsMatcher(p.values.get("--stairs")?.[0], p.values.get("--platforms")?.[0]), fps: num(p, "--fps"), clips: p.values.get("--clips"), headingEnd: num(p, "--heading-end"), warn: (w) => log(`   ⚠ ${w}`) })
-  for (const r of rows) log(`   🦶 ${r.clip.padEnd(22)} ${describeMarks(r.marks)}`)
-  const out = p.values.get("-o")?.[0] ?? input
-  const glb = await writeGlb(doc)
-  writeFileSync(out, glb)
-  log(`💾 wrote ${out}  (${rows.length} clips marked, ${((performance.now() - t0) / 1000).toFixed(1)}s)`)
-  return 0
-}
-
-const cmdBvh = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  const out = p.values.get("-o")?.[0]
-  if (!input || !out) { log("usage: bvh <model.glb> --clip <name> [--fps 30] -o out.bvh"); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { makeIO } = await import("./fbx/convert")
-  const { documentToBvh } = await import("./bvh/fromDocument")
-  const doc = await makeIO().read(input)
-  const r = documentToBvh(doc, { clip: p.values.get("--clip")?.[0], fps: num(p, "--fps") })
-  writeFileSync(out, r.text)
-  log(`💾 wrote ${out}  ("${r.report.clip}": ${r.report.joints} joints, ${r.report.frames} frames @ ${r.report.fps} fps)`)
-  return 0
-}
-
-const cmdConvert = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { convertFbx, mergeClipScene, loadClipSource, makeIO, writeGlb } = await import("./fbx/convert")
-  const clips = resolveInputs(p.values.get("--clips") ?? [], /\.(fbx|glb|uasset)$/i, false)
-  const clipNames = p.values.get("--clip-names")
-  const rename: Record<string, string> = {}
-  for (const r of p.values.get("--rename") ?? []) { const [ a, b ] = r.split("="); if (a && b) rename[a] = b }
-  const warn = (w: { level: string, message: string }): void => log(`   ${w.level === "warn" ? "⚠" : "ℹ"} ${w.message}`)
-  const t0 = performance.now()
-  log(`🔄 ${input}${clips.length ? ` + ${clips.length} clip file(s)` : ""}`)
-  let doc
-  let report: { clips: { name: string, source: string, duration: number, tracks: number, bound: number }[] } = { clips: [] }
-  const unrealOpts = { skeleton: p.values.get("--skeleton")?.[0], contentRoot: p.values.get("--content-root")?.[0], lod: num(p, "--lod-level") }
-  const unrealTex = { textures: !p.flags.has("--no-textures"), maxSize: num(p, "--max-size"), flipNormalGreen: !p.flags.has("--no-normal-flip") }
-  if (extname(input).toLowerCase() === ".uasset") {
-    // Unreal: a SkeletalMesh → mesh + skin + skeleton; a Skeleton or an AnimSequence → that
-    // skeleton (resolved from the pack for a clip) plus, for a clip, its own animation.
-    const { convertUnreal } = await import("./unreal/convertAsset")
-    const r = await convertUnreal(input, { clips, clipNames, rename, dropModelClips: p.flags.has("--drop-model-clips"), warn, ...unrealOpts, ...unrealTex })
-    doc = r.doc; report = r.report
-    log(`   ${r.info}`)
-    for (const s of r.textures?.slots ?? []) {
-      if (!s.material) continue
-      log(`   🎨 ${s.slot.padEnd(16)} ${s.material}${s.roles.length ? `  ${s.roles.join(" + ")}` : "  (no texture wired)"}${s.skipped.length ? `  · not in glTF: ${s.skipped.slice(0, 4).join(", ")}` : ""}`)
-    }
-  } else if (extname(input).toLowerCase() === ".bvh") {
-    // BVH (mocap, Kimodo's SOMA export): a skeleton-only rig — nodes, a skin with inverse binds, no
-    // mesh — plus the file's motion as one clip (named by --clip-names, else the file's stem)
-    const { bvhToDocument, describeBvh } = await import("./bvh/toDocument")
-    const r = bvhToDocument(readFileSync(input, "utf8"), { name: clipNames?.[0] ?? basename(input).replace(/\.bvh$/i, "") })
-    doc = r.doc
-    log(`   ${describeBvh(r.report)}`)
-  } else if (extname(input).toLowerCase() === ".fbx") {
-    const r = await convertFbx(input, {
-      clips, clipNames, rename, dropModelClips: p.flags.has("--drop-model-clips"), warn, ...unrealOpts,
-      unity: p.flags.has("--no-unity") ? false : (p.values.get("--unity-mats")?.[0] ?? true),
-      unityIndex: p.values.get("--unity-index")?.[0],
-    })
-    doc = r.doc; report = r.report
-    if (r.report.unity) {
-      const { describeUnityReport } = await import("./unity/materials")
-      for (const l of describeUnityReport(r.report.unity)) log(`   ${l}`)
-      if (r.report.unity.applied.length && r.report.unity.resolver) log(`   ℹ textures resolved via ${r.report.unity.resolver}`)
-    }
-  } else {
-    doc = await makeIO().read(input)
-    for (let i = 0; i < clips.length; i++) {
-      report.clips.push(...mergeClipScene(doc, await loadClipSource(clips[i], unrealOpts), basename(clips[i]), clipNames?.[i], rename, warn))
-    }
-  }
-  for (const c of report.clips) log(`   🎞  ${c.name.padEnd(24)} ${c.duration.toFixed(2)}s  ${c.bound}/${c.tracks} tracks  (${c.source})`)
-
-  // --merge-skins: modular pieces (shirt, gloves, boots…) onto this model's skeleton
-  const mergeFiles = p.values.get("--merge-skins") ?? []
-  if (mergeFiles.length) {
-    const { mergeSkins } = await import("./mergeSkins")
-    const { convertFbx } = await import("./fbx/convert")
-    const donors = []
-    for (const f of mergeFiles) {
-      if (!existsSync(f)) { console.error(`✗ not found: ${f}`); return 1 }
-      const d = extname(f).toLowerCase() === ".fbx"
-        ? (await convertFbx(f, { dropModelClips: true, warn, unity: p.flags.has("--no-unity") ? false : (p.values.get("--unity-mats")?.[0] ?? true), unityIndex: p.values.get("--unity-index")?.[0] })).doc
-        : await makeIO().read(f)
-      donors.push({ doc: d, label: basename(f) })
-    }
-    const mr = await mergeSkins(doc, donors, warn)
-    for (const d of mr.donors) log(`   🧵 ${d.label.padEnd(24)} ${d.meshes} skinned mesh(es) onto the ${mr.joints}-joint skeleton${d.missingJoints.length ? `  (${d.missingJoints.length} donor joint(s) not in the base${d.lostWeight > 0.01 ? `, ${d.lostWeight.toFixed(1)} weight lost` : ", unweighted"})` : ""}`)
-  }
-
-  // multi-variant prop files: list / keep / split
-  if (p.values.has("--list-nodes")) {
-    const { listNodes } = await import("./props")
-    const depth = parseInt(p.values.get("--list-nodes")?.[0] ?? "1", 10) || 1
-    log(`   nodes (depth ${depth}) — pick with --keep <name>:`)
-    for (const n of listNodes(doc, depth)) log(`   ${"  ".repeat(n.depth)}${n.name || "(unnamed)"}  ${n.meshes ? `${n.meshes} mesh · ${n.tris} tris · ${n.size.map((v) => v.toFixed(2)).join("×")} m` : n.children ? `${n.children} children` : "empty"}`)
-    return 0
-  }
-  const keepList = p.values.get("--keep") ?? []
-  if (keepList.length) {
-    const { keepNodes } = await import("./props")
-    const r = await keepNodes(doc, keepList, { ground: !p.flags.has("--no-ground") })
-    if (r.missing.length) { console.error(`✗ node(s) not in the file: ${r.missing.join(", ")}  (--list-nodes prints them)`); return 1 }
-    log(`   ✂  kept ${r.kept.join(", ")} · ${r.size.map((v) => v.toFixed(2)).join("×")} m${p.flags.has("--no-ground") ? "" : ` · re-origined (moved ${r.offset.map((v) => v.toFixed(2)).join(",")})`}`)
-  }
-  const wantsDoctor = p.flags.has("--fix") || p.flags.has("--ktx2") || p.flags.has("--ktx2-hq") || p.flags.has("--ktx2-uastc")
-    || p.flags.has("--fix-scale") || p.values.has("--scale") || p.values.has("--scale-to")
-    || p.flags.has("--unlit") || p.flags.has("--fix-emissive") || p.flags.has("--lightmap-uv")
-  if (wantsDoctor) {
-    const { analyzeDoc, applyPlan, reportPlan } = await import("./doctor/doctor")
-    const { ensureCodecs } = await import("./doctor/reduceGlbBones")
-    await ensureCodecs()
-    const opts = { ktx2: p.flags.has("--ktx2") || p.flags.has("--ktx2-hq") || p.flags.has("--ktx2-uastc"), ktx2Hq: p.flags.has("--ktx2-hq"), ktx2Uastc: p.flags.has("--ktx2-uastc"), maxSize: num(p, "--max-size"), target: num(p, "--target"), ...scaleOpts(p), ...shadingOpts(p), ...lightmapOpts(p) }
-    const plan = await analyzeDoc(doc, opts)
-    const rep = reportPlan(plan)
-    log(rep.text)
-    const res = await applyPlan(doc, plan, { ...opts, fixMetallic: p.flags.has("--fix-metallic"), progress: (d, t) => process.stdout.write(`\r   encoding ktx2… ${d}/${t}${d === t ? "\n" : ""}`) })
-    if (res.metallicZeroed) log(`   zeroed metallic on ${res.metallicZeroed} material(s)`)
-    if (res.emissiveCleared) log(`   cleared self-lit emissive on ${res.emissiveCleared} material(s)`)
-    if (res.unlit) log(`   ${res.unlit} material(s) → unlit (flat base colour, no lighting)`)
-    if (res.scaled !== 1) log(`   baked scale ×${+res.scaled.toPrecision(6)}`)
-    if (res.lightmapUv) log(`   lightmap UV: ${res.lightmapUv.charts} charts over ${res.lightmapUv.primitives} primitive(s) (xatlas ${res.lightmapUv.width}×${res.lightmapUv.height}); vertices ${res.lightmapUv.verticesBefore} → ${res.lightmapUv.verticesAfter}${res.lightmapUv.lodPrimitives ? `; ${res.lightmapUv.lodPrimitives} LOD primitive(s) took level 0's layout by projection (${res.lightmapUv.lodVertices} vertices)` : ''}`)
-    if (res.lod) {
-      for (const t of res.lod.tris) log(`   lod: ${t.name} ${t.levels.join(' / ')} tris`)
-      for (const b of res.lod.bones) log(`   lod bones: ${b.name} last level ${b.before} → ${b.after} joints`)
-      for (const k of res.lod.skipped) log(`   lod: ${k.name} level ${k.level} dropped — the simplifier reached only ${k.tris} tris (seams / hard surfaces; try a smaller ratio)`)
-      if (!res.lod.nodes) log(`   lod: no mesh with >= 2000 triangles (or the _LOD nodes are already there)`)
-    }
-  }
-  const out = p.values.get("-o")?.[0] ?? join(dirname(input), basename(input, extname(input)) + ".glb")
-  const { validateGlb, formatReport } = await import("./doctor/validateGlb")
-  const { probeDocument } = await import("./probe")
-  if (p.values.has("--split")) {
-    // one GLB per top-level node (the doctor passes above already ran on the whole document)
-    const { splitDoc, fileStem } = await import("./props")
-    const dir = p.values.get("--split")?.[0] ?? (p.values.has("-o") ? out.replace(/\.glb$/i, "") : join(dirname(input), basename(input, extname(input))))
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
-    const parts = await splitDoc(doc, { ground: !p.flags.has("--no-ground") })
-    let total = 0
-    for (const part of parts) {
-      const f = join(dir, fileStem(part.name) + ".glb")
-      const glb = await writeGlb(part.doc)
-      writeFileSync(f, glb)
-      total += glb.byteLength
-      const v = validateGlb(glb)
-      log(`   ${v.ok ? "✅" : "✗"} ${basename(f).padEnd(40)} ${part.size.map((x) => x.toFixed(2)).join("×")} m  ${(glb.byteLength / 1024).toFixed(0)} KB`)
-    }
-    log(`💾 wrote ${parts.length} file(s) → ${dir}  (${(total / 1024 / 1024).toFixed(2)} MB, ${((performance.now() - t0) / 1000).toFixed(1)}s)`)
-    return 0
-  }
-  const glb = await writeGlb(doc)
-  const dir = dirname(out)
-  if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
-  writeFileSync(out, glb)
-  log(formatReport(validateGlb(glb), out))
-  log(probeDocument(doc, out).split("\n").slice(1).join("\n"))
-  log(`💾 wrote ${out}  (${(glb.byteLength / 1024 / 1024).toFixed(2)} MB, ${((performance.now() - t0) / 1000).toFixed(1)}s)`)
-  return 0
-}
-
-const num = (p: Parsed, key: string): number | undefined => { const v = p.values.get(key)?.[0]; return v !== undefined ? parseInt(v, 10) : undefined }
-// Scale factors are fractional (--scale 0.01, --scale-to 1.8) — parseInt would silently truncate.
-const real = (p: Parsed, key: string): number | undefined => {
-  const v = p.values.get(key)?.[0]
-  if (v === undefined) return undefined
-  const n = Number(v)
-  if (!Number.isFinite(n) || n <= 0) throw new Error(`${key} needs a positive number, got "${v}"`)
-  return n
-}
-const scaleOpts = (p: Parsed) => ({ scale: real(p, "--scale"), scaleTo: real(p, "--scale-to"), fixScale: p.flags.has("--fix-scale") })
-const shadingOpts = (p: Parsed) => ({ unlit: p.flags.has("--unlit"), fixEmissive: p.flags.has("--fix-emissive") })
-const lightmapOpts = (p: Parsed) => ({ lightmapUv: p.flags.has("--lightmap-uv"), lightmapPadding: num(p, "--lightmap-padding"), lightmapIterations: num(p, "--lightmap-iterations") })
-const lodOpts = (p: Parsed) => ({ lod: (p.values.get("--lod") ?? []).flatMap((v) => v.split(",")).map(Number).filter((n) => n > 0 && n < 1), lodBones: p.flags.has("--lod-bones") })
-
-const cmdRetarget = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  const donorPath = p.values.get("--from")?.[0]
-  if (!input || !donorPath) { log(USAGE); return 2 }
-  for (const f of [ input, donorPath ]) if (!existsSync(f)) { console.error(`✗ not found: ${f}`); return 1 }
-  const { loadRig, rigFromDocument, checkUniformScale, hasSkin, rebindClips } = await import("./retarget/rig")
-  const { retarget, bindAccessors, analyzeFacing, facingMismatch } = await import("./retarget/retarget")
-  const { makeIO, writeGlb } = await import("./fbx/convert")
-  const { probeDocument } = await import("./probe")
-
-  const doc = await makeIO().read(input)
-  const target = rigFromDocument(doc, basename(input))
-  const unrealOpts = { skeleton: p.values.get("--skeleton")?.[0], contentRoot: p.values.get("--content-root")?.[0] }
-  const loadAny = async (path: string) => {
-    if (path.toLowerCase().endsWith(".uasset")) return (await import("./unreal/rig")).rigFromUnreal(path, unrealOpts)
-    if (path.toLowerCase().endsWith(".bvh")) {
-      const { bvhToDocument, describeBvh } = await import("./bvh/toDocument")
-      const r = bvhToDocument(readFileSync(path, "utf8"), { name: basename(path).replace(/\.bvh$/i, "") })
-      log(`   ${basename(path)}: ${describeBvh(r.report)}`)
-      return rigFromDocument(r.doc, basename(path))
-    }
-    return path.toLowerCase().endsWith(".fbx") ? loadRig(path) : rigFromDocument(await makeIO().read(path), basename(path))
-  }
-  let donor = await loadAny(donorPath)
-
-  // A skeleton-only clip file (a mocap pack's FBX: nodes + curves, no mesh) has no skin to classify
-  // and no bind to measure from: its clips are bound by bone name onto the rig it was animated on.
-  const donorRigPath = p.values.get("--donor-rig")?.[0]
-  if (donorRigPath) {
-    if (!existsSync(donorRigPath)) { console.error(`✗ not found: ${donorRigPath}`); return 1 }
-    const r = rebindClips(await loadAny(donorRigPath), donor)
-    log(`   📎 ${basename(donorPath)}: ${r.bound}/${r.total} bones bound to ${basename(donorRigPath)} by name${Math.abs(r.scale - 1) > 0.01 ? ` · the clip's skeleton is ×${(1 / r.scale).toFixed(2)} the rig's size (rotations taken, lengths the rig's)` : ""}${r.unbound.length ? ` (no bone: ${r.unbound.slice(0, 3).join(", ")}${r.unbound.length > 3 ? ` +${r.unbound.length - 3}` : ""})` : ""}`)
-    donor = r.rig
-  } else if (!hasSkin(donor) && !p.flags.has("--skeletons")) {
-    console.error(`✗ ${basename(donorPath)} carries no skin (a clip-only file) — name the rig it was animated on: --donor-rig <model.fbx|.glb>`)
-    return 2
-  }
-
-  // Clip assets that stand in for clips the donor rig file does not carry: Unity `.anim`
-  // AnimationClips, or Unreal `.uasset` AnimSequences (each on its own skeleton, bound by name).
-  const animFiles = resolveInputs(p.values.get("--anim") ?? [], /\.(anim|uasset)$/i, false)
-  if (animFiles.length) {
-    for (const f of animFiles) if (!existsSync(f)) { console.error(`✗ not found: ${f}`); return 1 }
-    const unity = animFiles.filter((f) => /\.anim$/i.test(f))
-    const unreal = animFiles.filter((f) => /\.uasset$/i.test(f))
-    const attached: import("./retarget/rig").Clip[] = []
-    const report: { name: string, bound: number, total: number, unbound: string[] }[] = []
-    if (unity.length) {
-      const { parseUnityAnim, attachUnityClips } = await import("./retarget/unityAnim")
-      const parsed = unity.map((f) => parseUnityAnim(readFileSync(f, "utf8"), basename(f).replace(/\.anim$/i, "")))
-      const r = attachUnityClips(donor, parsed)
-      attached.push(...r.clips); report.push(...r.report)
-    }
-    for (const f of unreal) {
-      const { loadUnreal } = await import("./unreal/index")
-      const { attachUnrealClips } = await import("./unreal/rig")
-      const u = loadUnreal(f, unrealOpts)
-      if (!u.anim) { console.error(`✗ ${basename(f)}: not an AnimSequence (${u.kind}) — --anim wants animation assets`); return 1 }
-      const r = attachUnrealClips(donor, u.skeleton, [ u.anim ])
-      attached.push(...r.clips); report.push(...r.report)
-    }
-    donor = { ...donor, clips: [ ...donor.clips, ...attached ] }
-    for (const r of report) {
-      log(`   📎 ${r.name.padEnd(20)} ${r.bound}/${r.total} curves bound${r.unbound.length ? `  (no bone: ${r.unbound.slice(0, 3).join(", ")}${r.unbound.length > 3 ? ` +${r.unbound.length - 3}` : ""})` : ""}`)
-    }
-  }
-
-  if (p.flags.has("--skeletons")) {
-    // Depth-first, parents before children — the shape you actually read a skeleton in.
-    const col = (rig: { names: string[], parents: number[], bind: { fromSkin: boolean[] } }): string[] => {
-      const kids: number[][] = rig.names.map(() => [])
-      const roots: number[] = []
-      rig.parents.forEach((par, i) => (par >= 0 ? kids[par].push(i) : roots.push(i)))
-      const out: string[] = []
-      const walk = (i: number, d: number): void => {
-        out.push(`${"  ".repeat(d)}${rig.names[i] || "?"}${rig.bind.fromSkin[i] ? " *" : ""}`)
-        for (const c of kids[i]) walk(c, d + 1)
-      }
-      roots.forEach((r) => walk(r, 0))
-      return out
-    }
-    const a = col(target), b = col(donor)
-    log(`
-${`TARGET ${basename(input)} (${target.names.length})`.padEnd(46)}DONOR ${basename(donorPath)} (${donor.names.length})`)
-    log(`${"(* = bound by a skin)".padEnd(46)}(* = bound by a skin)`)
-    for (let i = 0; i < Math.max(a.length, b.length); i++) log(`${(a[i] ?? "").slice(0, 44).padEnd(46)}${b[i] ?? ""}`)
-    log(`
-donor clips: ${donor.clips.map((c) => `"${c.name}" ${c.duration.toFixed(2)}s`).join(", ") || "none"}`)
-    const { classifyBiped, describeBiped } = await import("./retarget/humanoid")
-    for (const [ label, rig ] of [ [ "target", target ], [ "donor", donor ] ] as const) {
-      try { log(`${label} reads as a humanoid: ${describeBiped(rig, classifyBiped(rig))}`) } catch { /* not a biped — fine */ }
-    }
-    return 0
-  }
-
-  // Avatars: a humanoid rig's bones in the canon — given (`.avatar.json` / Unity `.meta`) or from shape.
-  const { avatarFromRig, avatarFromUnity, avatarFromFile, parseUnityAvatar, mapAvatars, describeHumanoidMap, describeBiped, classifyBiped, isBiped } = await import("./retarget/humanoid")
-  type Avatar = import("./retarget/humanoid").Avatar
-  const loadAvatar = (rig: import("./retarget/rig").Rig, file: string | undefined): Avatar | null => {
-    if (!file) return isBiped(rig) ? avatarFromRig(rig) : null
-    if (!existsSync(file)) throw new Error(`not found: ${file}`)
-    const text = readFileSync(file, "utf8")
-    return /\.meta$/i.test(file) ? avatarFromUnity(rig, parseUnityAvatar(text)) : avatarFromFile(rig, JSON.parse(text))
-  }
-
-  type MapSpec = {
-    root?: string, bones: Record<string, string>, alignTo?: Record<string, string[]>,
-    align?: Record<string, "keep" | "direction" | string[]>, legs?: string[], ik?: boolean,
-    donorRef?: "bind" | "auto" | { clip: string, time?: number },
-    twist?: Record<string, string>,
-    /** Both avatars of a humanoid map — reloaded so `--map file.json` keeps the humanoid treatment. */
-    avatars?: { target: import("./retarget/humanoid").AvatarFile, donor: import("./retarget/humanoid").AvatarFile },
-  }
-  let humanoid: { target: Avatar, donor: Avatar } | undefined
-  const mapPath = p.values.get("--map")?.[0]
-  const autoOut = p.values.get("--auto-map")
-  let spec: MapSpec
-  const avatarFile = p.values.get("--avatar")?.[0], donorAvatarFile = p.values.get("--donor-avatar")?.[0]
-  if (autoOut !== undefined || mapPath === "auto" || avatarFile || donorAvatarFile) {
-    let tAv: Avatar | null, dAv: Avatar | null
-    try { tAv = loadAvatar(target, avatarFile); dAv = loadAvatar(donor, donorAvatarFile) } catch (e) { console.error(`✗ ${(e as Error).message}`); return 1 }
-    if (tAv && dAv) {
-      // Humanoids: both avatars joined on the canon (src/retarget/humanoid.ts).
-      const hm = mapAvatars(tAv, dAv)
-      log(`🧭 humanoid map ${basename(input)} ← ${basename(donorPath)}`)
-      for (const [ label, rig, file ] of [ [ "target", target, avatarFile ], [ "donor", donor, donorAvatarFile ] ] as const) {
-        try { log(`   ${label}: ${file ? `avatar from ${basename(file)} · ` : ""}${describeBiped(rig, classifyBiped(rig))}`) } catch { log(`   ${label}: avatar from ${basename(file ?? "?")} (shape did not classify)`) }
-      }
-      for (const l of describeHumanoidMap(tAv, dAv, hm)) log(l)
-      humanoid = { target: tAv, donor: dAv }
-      const { avatarToFile } = await import("./retarget/humanoid")
-      spec = { _comment: `humanoid map ${basename(input)} ← ${basename(donorPath)} — target and donor avatars joined on the Unity/VRM canon; review before trusting`, root: hm.root, bones: hm.map, legs: hm.legs, twist: tAv.twist, avatars: { target: avatarToFile(tAv), donor: avatarToFile(dAv) } } as MapSpec
-    } else if (tAv || dAv) {
-      console.error(`✗ ${tAv ? "the donor" : "the target"} does not read as a humanoid while ${tAv ? "the target" : "the donor"} does — a biped↔quadruped retarget needs a hand-written map`)
-      return 1
-    } else {
-      // Quadrupeds: map from skeleton SHAPE (src/retarget/automap.ts) — a starting point the user reads and corrects.
-      const { autoMap, describeSkeleton } = await import("./retarget/automap")
-      const am = autoMap(target, donor)
-      log(`🧭 auto-map ${basename(input)} ← ${basename(donorPath)}`)
-      log(`   target: ${describeSkeleton(target, am.target)}`)
-      log(`   donor:  ${describeSkeleton(donor, am.donor)}`)
-      for (const l of am.lines) log(l)
-      spec = { _comment: `auto-mapped ${basename(input)} ← ${basename(donorPath)} by skeleton shape — review before trusting`, root: am.root, bones: am.map, legs: am.legs } as MapSpec
-    }
-    if (autoOut !== undefined) {
-      const out = autoOut[0] ?? input.replace(/\.glb$/i, "") + "-from-" + basename(donorPath).replace(/\.[^.]+$/, "") + ".map.json"
-      writeFileSync(out, JSON.stringify(spec, null, 2) + "\n")
-      log(`💾 wrote ${out}  (${Object.keys(spec.bones).length} bones) — edit it, then: retarget … --map ${basename(out)}`)
-      return 0
-    }
-  } else {
-    if (!mapPath) { console.error("✗ --map <map.json> is required (--map auto / --auto-map [out.json] to derive one from the skeletons, --skeletons to list them)"); return 2 }
-    if (!existsSync(mapPath)) { console.error(`✗ not found: ${mapPath}`); return 1 }
-    spec = JSON.parse(readFileSync(mapPath, "utf8")) as MapSpec
-    if (!spec.bones) { console.error(`✗ ${mapPath} has no "bones" object`); return 2 }
-    if (spec.avatars) {
-      try { humanoid = { target: avatarFromFile(target, spec.avatars.target), donor: avatarFromFile(donor, spec.avatars.donor) } }
-      catch (e) { log(`   ⚠ ${basename(mapPath)} carries avatars that do not fit these rigs (${(e as Error).message}) — plain map`) }
-    }
-  }
-
-  checkUniformScale(target); checkUniformScale(donor)
-  const t0 = performance.now()
-  log(`🔁 ${basename(input)} ← ${basename(donorPath)}`)
-
-  // A retarget is only meaningful if both rigs agree which way is forward; measure it from the
-  // skeleton shape (automap.classify), falling back to the mapped head/tail bones, and turn the
-  // donor to match.
-  let donorYawDeg = 0
-  {
-    let fa: { forward: number[] } | null = null, da: { forward: number[] } | null = null
-    try {
-      // A biped faces where its toes point (its long horizontal axis is the ARM SPAN in a T-pose);
-      // a quadruped faces along its body.
-      const { classify } = await import("./retarget/automap")
-      const facingOf = (rig: import("./retarget/rig").Rig): { forward: number[] } => { try { return classifyBiped(rig) } catch { return classify(rig) } }
-      fa = facingOf(target); da = facingOf(donor)
-    } catch {
-      const spine = Object.entries(spec.bones)
-      const headPair = spine.find(([ t ]) => /head/i.test(t)), tailPair = spine.find(([ t ]) => /tail|root|hip|pelvis/i.test(t))
-      if (headPair && tailPair) { fa = analyzeFacing(target, [ headPair[0], tailPair[0] ]); da = analyzeFacing(donor, [ headPair[1], tailPair[1] ]) }
-    }
-    if (fa && da) {
-      const off = facingMismatch(fa.forward as [number, number, number], da.forward as [number, number, number])
-      // Signed yaw about +Y that turns the donor's forward onto the target's.
-      const signed = Math.atan2(da.forward[2] * fa.forward[0] - da.forward[0] * fa.forward[2], da.forward[0] * fa.forward[0] + da.forward[2] * fa.forward[2]) * 180 / Math.PI
-      if (off > 2) donorYawDeg = signed
-      log(`   facing: target [${fa.forward.map((x) => x.toFixed(2))}] vs donor [${da.forward.map((x) => x.toFixed(2))}] — ${off.toFixed(1)}° apart${off > 2 ? ` → turning the donor by ${signed.toFixed(1)}°` : ""}`)
-    }
-  }
-  if (target.bind.scale !== 1) log(`   ℹ target skin's bind space is ×${+(1 / target.bind.scale).toPrecision(4)} of node space — bind pose rescaled ×${+target.bind.scale.toPrecision(4)} to match`)
-  if (donor.bind.scale !== 1) log(`   ℹ donor skin's bind space is ×${+(1 / donor.bind.scale).toPrecision(4)} of node space — bind pose rescaled ×${+donor.bind.scale.toPrecision(4)} to match`)
-
-  if (!p.flags.has("--keep-clips")) for (const a of doc.getRoot().listAnimations()) a.dispose()
-  const prefix = p.values.get("--prefix")?.[0] ?? ""
-  // --clip-names renames the PRODUCED clips positionally, same convention as `convert`.
-  const names = p.values.get("--clip-names")
-  let produced = 0
-  // The avatar's transfer block (the studio's decisions) supplies the defaults; flags override.
-  const tr = humanoid?.target.transfer
-  if (tr && Object.keys(tr).length) {
-    const parts: string[] = []
-    if (tr.rootMotion) parts.push(`root motion ${tr.rootMotion}`)
-    if (tr.plant !== undefined) parts.push(tr.plant ? "plant" : "no plant")
-    if (tr.hands) parts.push("hands IK")
-    if (tr.twist !== undefined) parts.push(`twist ${tr.twist}`)
-    for (const s of [ "Left", "Right" ] as const) if (tr.roll?.[s]) parts.push(`${s[0]} roll ${tr.roll[s]! > 0 ? "+" : ""}${tr.roll[s]}°`)
-    const keep = Object.entries(tr.align ?? {}).filter(([ , v ]) => v === "keep").map(([ k ]) => k), al = Object.entries(tr.align ?? {}).filter(([ , v ]) => v === "align").map(([ k ]) => k)
-    if (keep.length) parts.push(`keep ${keep.join(", ")}`)
-    if (al.length) parts.push(`align ${al.join(", ")}`)
-    log(`   avatar transfer: ${parts.join(" · ")}`)
-  }
-  const { stairsMatcher } = await import("./retarget/marks")
-  const rep = retarget(target, donor, spec.bones, spec.root ?? null, {
-    align: (p.values.get("--align")?.[0] as "none" | "bone-direction" | undefined) ?? "bone-direction",
-    alignTo: spec.alignTo,
-    alignBones: spec.align,
-    donorYawDeg,
-    donorRef: (() => { const v = p.values.get("--donor-ref")?.[0]; return v === undefined ? spec.donorRef : v === "bind" || v === "auto" ? v : { clip: v } })(),
-    ik: p.values.get("--ik")?.[0] === "none" || spec.ik === false ? "none" : p.values.get("--ik")?.[0] === "hands" || (p.values.get("--ik") === undefined && tr?.hands) ? "legs+hands" : "legs",
-    rootMotion: (p.values.get("--root-motion")?.[0] as import("./retarget/retarget").RootMotion | undefined) ?? tr?.rootMotion ?? "auto",
-    headingEnd: num(p, "--heading-end"),
-    rootRotation: (p.values.get("--root-rotation")?.[0] as "none" | "yaw" | undefined) ?? "none",
-    plant: p.flags.has("--no-plant") ? false : tr?.plant ?? true,
-    footStance: p.values.get("--foot-stance")?.[0] as "target" | "donor" | undefined,
-    stairs: stairsMatcher(p.values.get("--stairs")?.[0], p.values.get("--platforms")?.[0]),
-    twist: (() => { const v = p.values.get("--twist")?.[0]; return v === undefined ? (tr?.twist !== undefined ? (tr.twist > 0 ? tr.twist : false) : 0.5) : v === "off" ? false : Number(v) })(),
-    legs: spec.legs,
-    fps: num(p, "--fps"),
-    epsilon: real(p, "--epsilon"),
-    bodyClearance: real(p, "--body-clearance"),
-    epsilonDeg: real(p, "--epsilon-deg"),
-    rootScale: real(p, "--root-scale"),
-    clips: p.values.get("--clips"),
-    rename: names?.length || prefix ? (n: string) => prefix + (names?.[produced++] ?? n) : undefined,
-    humanoid,
-    warn: (w) => log(`   ⚠ ${w}`),
-  })
-  if (humanoid) log(`   humanoid: torso/legs keep, arms + fingers aligned (≥ 8°)${rep.roll.length ? ` · palm roll ${rep.roll.map((r) => `${r.side[0]} ${r.degrees.toFixed(0)}° (${r.via})`).join(", ")}` : ""}${rep.rootTranslateOnly ? " · root takes the hips' travel only" : ""}`)
-  if (rep.bindGap.donor.worst > 1e-3) log(`   ℹ donor's node pose sits ${rep.bindGap.donor.worst.toFixed(3)}m from its bind pose (worst: ${rep.bindGap.donor.bone}) — anchoring on the bind pose`)
-  log(`   ${rep.mapped.length} bones mapped · ${rep.align.length} direction-aligned (worst ${rep.align[0]?.degrees.toFixed(0) ?? 0}° on ${rep.align[0]?.bone ?? "-"})${rep.underThreshold.length ? ` · ${rep.underThreshold.length} under 8° kept (worst ${rep.underThreshold[0].degrees.toFixed(0)}° on ${rep.underThreshold[0].bone})` : ""} · ${rep.kept.length} keep bind (${rep.kept.join(", ") || "-"})`)
-  log(`   donor reference: ${rep.donorRef} (leg directions ${rep.legDisagreement.toFixed(0)}° apart between the binds) · target binds ${rep.stance ? "in a stance — legs keep it" : "posed — legs aligned to the donor"}`)
-  log(`   root ${rep.root ? `${rep.root.target}←${rep.root.donor} ×${+rep.rootScale.toPrecision(3)} (from ${rep.rootScaleFrom})` : "none"}${rep.ground ? ` · ground target ${rep.ground.target.toFixed(3)}m / donor ${rep.ground.donor.toFixed(3)}m` : ""}`)
-  if (rep.legs.length) for (const l of rep.legs) log(`   ${l.isFoot ? "🦶" : "✋"} ${l.effector.padEnd(14)} ← ${l.donorEffector.padEnd(12)} chain ${l.chain.join("→")}${l.contact !== l.effector ? `  contact ${l.contact}` : ""}  ×${l.ratio.toFixed(3)}${l.planted ? `  planted ${l.planted} frames` : ""}${l.shortfall > 1e-4 ? `  ⚠ out of reach by up to ${(l.shortfall * 1000).toFixed(0)}mm` : ""}`)
-  else if (p.values.get("--ik")?.[0] !== "none" && spec.ik !== false) log(`   ℹ no leg chains detected — feet follow FK only (name them in the map: "legs": [ … ])`)
-  if (rep.root) log(`   root motion: ${rep.rootMotion}${rep.hipsBob ? ` · hips carry the ${rep.hipsBob === "donor" ? "donor's own bob" : "vertical bob"}` : ""}`)
-  if (rep.twist.length) log(`   twist helpers: ${rep.twist.map((t) => `${t.bone} (${(t.at * 100).toFixed(0)}% of ${t.of})`).join(", ")}`)
-  if (rep.bridges.length) log(`   bridged (interpolated between mapped bones): ${rep.bridges.join(", ")}`)
-  if (rep.unmappedTarget.length) log(`   unmapped (left at rest): ${rep.unmappedTarget.join(", ")}`)
-  for (const c of rep.clips) {
-    const reach = c.events.filter((e) => e.kind === "reach"), below = c.events.filter((e) => e.kind === "below")
-    log(`   🎞  ${c.name.padEnd(22)} ${c.duration.toFixed(2)}s  ${c.frames} frames → ${c.keys} keys${reach.length ? `  ⚠ ${reach.length}× out of reach (${(Math.max(...reach.map((e) => e.value ?? 0)) * 1000).toFixed(0)} mm)` : ""}${below.length ? `  ⚠ ${below.length}× toe under the ground (${(Math.max(...below.map((e) => e.value ?? 0)) * 1000).toFixed(0)} mm)` : ""}`)
-  }
-
-  bindAccessors(doc)
-  const out = p.values.get("-o")?.[0] ?? input.replace(/\.glb$/i, ".retargeted.glb")
-  const dir = dirname(out)
-  if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
-  const glb = await writeGlb(doc)
-  writeFileSync(out, glb)
-  const { validateGlb, formatReport } = await import("./doctor/validateGlb")
-  log(formatReport(validateGlb(glb), out))
-  log(probeDocument(doc, out).split("\n").slice(1).join("\n"))
-  log(`💾 wrote ${out}  (${(glb.byteLength / 1024 / 1024).toFixed(2)} MB, ${((performance.now() - t0) / 1000).toFixed(1)}s)`)
-  return 0
-}
-
-const cmdAvatar = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { loadRig, rigFromDocument } = await import("./retarget/rig")
-  const { classifyBiped, avatarFromBiped, avatarFromUnity, avatarToFile, parseUnityAvatar, describeBiped, HUMAN_BONES } = await import("./retarget/humanoid")
-  const { makeIO } = await import("./fbx/convert")
-  const rig = /\.uasset$/i.test(input) ? (await import("./unreal/rig")).rigFromUnreal(input, { skeleton: p.values.get("--skeleton")?.[0], contentRoot: p.values.get("--content-root")?.[0] })
-    : /\.fbx$/i.test(input) ? await loadRig(input) : rigFromDocument(await makeIO().read(input), basename(input))
-  let shape: ReturnType<typeof avatarFromBiped> | null = null
-  try {
-    const b = classifyBiped(rig)
-    shape = avatarFromBiped(rig, b)
-    log(`🧍 ${basename(input)}: ${describeBiped(rig, b)}`)
-    const groups: [string, string[]][] = [
-      [ "torso", [ "Hips", "Spine", "Chest", "UpperChest", "Neck", "Head", "Jaw", "LeftEye", "RightEye" ] ],
-      [ "left arm", [ "LeftShoulder", "LeftUpperArm", "LeftLowerArm", "LeftHand" ] ], [ "right arm", [ "RightShoulder", "RightUpperArm", "RightLowerArm", "RightHand" ] ],
-      [ "left leg", [ "LeftUpperLeg", "LeftLowerLeg", "LeftFoot", "LeftToes" ] ], [ "right leg", [ "RightUpperLeg", "RightLowerLeg", "RightFoot", "RightToes" ] ],
-    ]
-    type HB = import("./retarget/humanoid").HumanBone
-    const av = shape
-    for (const [ g, keys ] of groups) log(`   ${g}: ${keys.filter((k) => av.bones[k as HB]).map((k) => `${k}=${av.bones[k as HB]}`).join(" ")}`)
-    const fingers = HUMAN_BONES.filter((k) => k.includes(" ") && shape!.bones[k])
-    if (fingers.length) log(`   fingers: ${fingers.length} phalanges (${fingers.filter((k) => k.endsWith("Proximal")).map((k) => shape!.bones[k]).join(", ")})`)
-    if (Object.keys(shape.twist).length) log(`   twist helpers: ${Object.entries(shape.twist).map(([ t, of ]) => `${t}→${of}`).join(", ")}`)
-    if (shape.bridged.length) log(`   bridged: ${shape.bridged.join(", ")}`)
-    if (b.helpers.length) log(`   not part of the body (${b.helpers.length}): ${b.helpers.map((i) => rig.names[i]).slice(0, 16).join(", ")}${b.helpers.length > 16 ? " …" : ""}`)
-    for (const n of shape.notes) log(`   ⚠ ${n}`)
-  } catch (e) {
-    log(`✗ ${basename(input)} does not read as a humanoid: ${(e as Error).message}`)
-  }
-  const metaPath = p.values.get("--meta")?.[0]
-  let unity: ReturnType<typeof avatarFromUnity> | null = null
-  if (metaPath) {
-    if (!existsSync(metaPath)) { console.error(`✗ not found: ${metaPath}`); return 1 }
-    unity = avatarFromUnity(rig, parseUnityAvatar(readFileSync(metaPath, "utf8")))
-    for (const n of unity.notes) log(`   ⚠ .meta: ${n}`)
-    if (shape) {
-      let agree = 0
-      const differ: string[] = []
-      for (const k of HUMAN_BONES) {
-        const a = shape.bones[k], m = unity.bones[k]
-        if (a === m) { if (a) agree++; continue }
-        differ.push(`${k}: shape=${a ?? "-"} .meta=${m ?? "-"}`)
-      }
-      log(`   vs ${basename(metaPath)}: ${agree} bones agree${differ.length ? `, ${differ.length} differ:` : ""}`)
-      for (const d of differ) log(`      ${d}`)
-    }
-  }
-  const chosen = unity ?? shape
-  if (!chosen) return 1
-  const out = p.values.get("-o")?.[0]
-  if (out) {
-    writeFileSync(out, JSON.stringify(avatarToFile(chosen), null, 2) + "\n")
-    log(`💾 wrote ${out}  (${Object.keys(chosen.bones).length} bones, ${unity ? "Unity's map" : "from shape"}) — retarget … --avatar ${basename(out)}`)
-  }
-  return 0
-}
-
-const cmdMirror = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  const { makeIO } = await import("./fbx/convert")
-  const { mirrorClips } = await import("./retarget/mirror")
-  const io = makeIO()
-  const doc = await io.read(input)
-  const clips = p.values.get("--clips")
-  const suffix = p.values.get("--suffix")?.[0] ?? "_M"
-  const axis = p.values.get("--axis")?.[0] as "x" | "y" | "z" | undefined
-  const rep = mirrorClips(doc, { clips: clips && clips.length ? clips : undefined, rename: (n) => `${n}${suffix}`, axis, log })
-  log(`== mirror across ${rep.axis.toUpperCase()} = 0: ${rep.pairs.length} bone pairs, ${rep.self.length} on the plane; worst pair mismatch ${(rep.worst.error * 100).toFixed(1)} cm (${rep.worst.bone})`)
-  if (rep.worst.error > 0.05) log(`   ⚠ a pair is off by more than 5 cm — the bind pose is not symmetric, or a bone is paired wrongly`)
-  if (!rep.clips.length) { log(`   ✗ no clip matched`); return 1 }
-  const output = p.values.get("-o")?.[0] ?? input
-  await io.write(output, doc)
-  log(`💾 wrote ${output} (+${rep.clips.length} clips)`)
-  return 0
-}
-
-const cmdUnpack = async (p: Parsed): Promise<number> => {
-  const pkg = p.positionals[0]
-  if (!pkg) { log(USAGE); return 2 }
-  if (!existsSync(pkg)) { console.error(`✗ not found: ${pkg}`); return 1 }
-  const { indexUnityPackage, writeUnityIndex, readUnityIndex, extractUnityPackage, INDEX_NAME } = await import("./unity/unpack")
-  const outDir = p.values.get("-o")?.[0] ?? join(dirname(pkg), basename(pkg, extname(pkg)))
-  const t0 = performance.now()
-  const indexFile = join(outDir, INDEX_NAME)
-  let index
-  if (existsSync(indexFile)) { index = readUnityIndex(indexFile); log(`📇 ${index.size} assets (cached ${indexFile})`) }
-  else {
-    log(`📇 indexing ${pkg} …`)
-    index = await indexUnityPackage(pkg, (n, a) => process.stdout.write(`\r   ${n} entries, ${a} assets`))
-    process.stdout.write("\r")
-    writeUnityIndex(outDir, index)
-    log(`   ${index.size} assets → ${indexFile}`)
-  }
-  const only = (p.values.get("--only") ?? []).map((r) => new RegExp(r, "i"))
-  if (p.flags.has("--list")) {
-    for (const [ , path ] of index) if (!only.length || only.some((r) => r.test(path))) log(path)
-    return 0
-  }
-  log(`📦 extracting${only.length ? ` (${only.length} pattern(s))` : ""} → ${outDir}`)
-  const r = await extractUnityPackage(pkg, index, outDir, { only, progress: (f, b) => process.stdout.write(`\r   ${f} files, ${(b / 1e6).toFixed(0)} MB`) })
-  process.stdout.write("\r")
-  log(`   ${r.files} files written (${(r.bytes / 1e6).toFixed(1)} MB) of ${r.matched} matching, ${((performance.now() - t0) / 1000).toFixed(0)}s`)
-  return 0
-}
-
-const cmdProbe = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { probeFile } = await import("./probe")
-  log(await probeFile(input))
-  if (p.values.has("--filmstrip")) {
-    if (extname(input).toLowerCase() === ".fbx") { console.error("✗ --filmstrip wants a GLB (convert first)"); return 2 }
-    const { renderFilmstrip } = await import("./filmstrip")
-    const { makeIO } = await import("./fbx/convert")
-    const doc = await makeIO().read(input)
-    const only = p.values.get("--clip")?.[0]
-    const clips = doc.getRoot().listAnimations().map((a) => a.getName()).filter((n) => !only || n === only)
-    if (only && clips.length === 0) { console.error(`✗ no clip "${only}"`); return 1 }
-    const stem = p.values.get("--filmstrip")?.[0] ?? input.replace(/\.glb$/i, "")
-    const targets = clips.length ? clips : [ null ]
-    const opts = { frames: num(p, "--frames") ?? 6, view: (p.values.get("--view")?.[0] ?? "side") as import("./filmstrip").FilmstripView, cell: num(p, "--cell"), bones: p.flags.has("--bones") }
-    for (const clip of targets) {
-      const r = renderFilmstrip(doc, { ...opts, clip })
-      const file = targets.length === 1 && /\.png$/i.test(stem) ? stem : `${stem.replace(/\.png$/i, "")}.${(clip ?? "rest").replace(/[^\w.-]+/g, "_")}.png`
-      writeFileSync(file, r.png)
-      log(`🖼  ${file}  ${r.label}`)
-    }
-  }
-  return 0
-}
-
-const cmdScene = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { log(USAGE); return 2 }
-  if (!existsSync(input)) { console.error(`✗ not found: ${input}`); return 1 }
-  const { importUnityScene, describeSceneImport } = await import("./unity/scene")
-  const regionRaw = p.values.get("--region")?.[0]
-  let region: [number, number, number, number] | undefined
-  if (regionRaw !== undefined) {
-    const v = regionRaw.split(",").map(Number)
-    if (v.length !== 4 || v.some((x) => !Number.isFinite(x))) { console.error(`✗ --region wants x0,z0,x1,z1 (Unity metres), got "${regionRaw}"`); return 2 }
-    region = [ Math.min(v[0], v[2]), Math.min(v[1], v[3]), Math.max(v[0], v[2]), Math.max(v[1], v[3]) ]
-  }
-  const hand = p.values.get("--handedness")?.[0] ?? "x"
-  if (![ "x", "z", "none" ].includes(hand)) { console.error(`✗ --handedness wants x | z | none`); return 2 }
-  const t0 = performance.now()
-  const r = importUnityScene(input, {
-    indexFile: p.values.get("--index")?.[0],
-    handedness: hand as "x" | "z" | "none",
-    filter: p.values.get("--filter")?.[0] ? new RegExp(p.values.get("--filter")![0], "i") : undefined,
-    group: p.values.get("--group")?.[0],
-    region,
-    includeInactive: p.flags.has("--include-inactive"),
-  })
-  log(`🗺  ${input}`)
-  for (const l of describeSceneImport(r)) log(`   ${l}`)
-  const out = p.values.get("-o")?.[0] ?? input.replace(/\.unity$/i, "") + ".level.json"
-  const dir = dirname(out)
-  if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true })
-  writeFileSync(out, JSON.stringify(r, null, 1) + "\n")
-  log(`💾 wrote ${out}  (${r.instances.length} instances, ${((performance.now() - t0) / 1000).toFixed(1)}s) — frame: ${r.frame}`)
-  return 0
-}
-
-// Resolve positionals to concrete .glb files — accepts plain files, directories, and globs (*.glb,
-// dir/**/*.glb). Generated outputs (.ktx2.glb/.fixed.glb) are skipped when EXPANDING a glob/dir, but
-// kept if named explicitly (e.g. to --dump one).
-const resolveInputs = (args: string[], ext = /\.glb$/i, skipGenerated = true): string[] => {
-  const out: string[] = []
-  const keep = (f: string): void => { if (ext.test(f) && !(skipGenerated && /\.(ktx2|fixed)\.glb$/i.test(f))) out.push(f) }
-  // minimal glob (runs under Node too — the lecodes CLI is a Node binary): a directory, `dir/*.glb`,
-  // or `dir/**/*.glb`
-  const walk = (dir: string, recursive: boolean, pattern: RegExp): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const p = join(dir, entry.name).replace(/\\/g, "/")
-      if (entry.isDirectory()) { if (recursive) walk(p, true, pattern) }
-      else if (pattern.test(entry.name)) keep(p)
-    }
-  }
-  const toRegex = (glob: string): RegExp =>
-    new RegExp("^" + glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$", "i")
-  for (const raw of args) {
-    const a = raw.replace(/\\/g, "/")
-    if (/[*?]/.test(a)) {
-      const segs = a.split("/")
-      const last = segs.pop()!
-      const recursive = segs[segs.length - 1] === "**"
-      if (recursive) segs.pop()
-      const dir = segs.join("/") || "."
-      if (existsSync(dir)) walk(dir, recursive, toRegex(last))
-    } else if (existsSync(a) && statSync(a).isDirectory()) {
-      walk(a.replace(/\/+$/, ""), false, ext)
-    } else out.push(a)
-  }
-  return [ ...new Set(out) ]
-}
-
-const cmdDoctor = async (p: Parsed): Promise<number> => {
-  const files = resolveInputs(p.positionals)
-  if (files.length === 0) { log(USAGE); return 2 }
-  const { analyzeDoc, applyPlan, reportPlan, dumpTextures, outputFor, findToktx, checkToktx, kb } = await import("./doctor/doctor")
-  const { ensureCodecs, makeIO } = await import("./doctor/reduceGlbBones")
-  const { validateGlb, formatReport } = await import("./doctor/validateGlb")
-  const useKtx2 = p.flags.has("--ktx2") || p.flags.has("--ktx2-hq") || p.flags.has("--ktx2-uastc")
-  const fixMetallic = p.flags.has("--fix-metallic")
-  const sh = shadingOpts(p)
-  const sc = scaleOpts(p)
-  const lmo = lightmapOpts(p)
-  const lod = lodOpts(p)
-  const wantsScale = sc.fixScale || sc.scale !== undefined || sc.scaleTo !== undefined
-  const doFix = p.flags.has("--fix") || useKtx2 || fixMetallic || wantsScale || sh.unlit || sh.fixEmissive || lmo.lightmapUv || lod.lod.length > 0
-  const dumpMode = p.values.has("--dump")
-  const dumpVal = p.values.get("--dump")?.[0] ?? null
-  const oVal = p.values.get("-o")?.[0] ?? null
-  const opts = { ktx2: useKtx2, ktx2Hq: p.flags.has("--ktx2-hq"), ktx2Uastc: p.flags.has("--ktx2-uastc"), maxSize: num(p, "--max-size"), target: num(p, "--target"), ...sc, ...sh, ...lmo, ...lod }
-  let toktx = ""
-  if (useKtx2) {
-    toktx = findToktx()
-    const ver = checkToktx(toktx)
-    if (!ver) { console.error(`✗ toktx not found (looked at $KTX_TOKTX, %LOCALAPPDATA%\\Programs\\KTX-Software, PATH).\n  Install KTX-Software or set KTX_TOKTX=<path to toktx.exe>.`); return 2 }
-    log(`   using ${ver}`)
-  }
-  await ensureCodecs()
-  const io = makeIO()
-  if (files.length > 1) log(`Processing ${files.length} files…`)
-  let exitCode = 0
-  for (const input of files) {
-    if (!existsSync(input)) { console.error(`\n✗ not found: ${input}`); exitCode = 1; continue }
-    const doc = await io.read(input)
-    if (dumpMode) { await dumpTextures(doc, dumpVal && files.length === 1 ? dumpVal : input.replace(/\.glb$/i, "-textures")); continue }
-    const plan = await analyzeDoc(doc, opts)
-    const rep = reportPlan(plan)
-    log(`\n🔍 ${input}`)
-    log(rep.text)
-    log(`   ${rep.lossless} lossless · ${rep.lossy} lossy · ${rep.blocking} blocking`)
-    if (rep.blocking > 0) exitCode = 1
-    if (!doFix) { if (rep.lossless + rep.lossy > 0) log(`   run with --fix or --ktx2 to apply`); continue }
-    const res = await applyPlan(doc, plan, { ...opts, fixMetallic, toktx: toktx || undefined, progress: (d, t) => process.stdout.write(`\r   encoding ktx2… ${d}/${t}${d === t ? "\n" : ""}`) })
-    if (res.metallicZeroed) log(`   zeroed metallic on ${res.metallicZeroed} material(s)`)
-    if (res.emissiveCleared) log(`   cleared self-lit emissive on ${res.emissiveCleared} material(s)`)
-    if (res.unlit) log(`   ${res.unlit} material(s) → unlit (flat base colour, no lighting)`)
-    if (res.scaled !== 1) log(`   baked scale ×${+res.scaled.toPrecision(6)}`)
-    if (res.lightmapUv) log(`   lightmap UV: ${res.lightmapUv.charts} charts over ${res.lightmapUv.primitives} primitive(s) (xatlas ${res.lightmapUv.width}×${res.lightmapUv.height}); vertices ${res.lightmapUv.verticesBefore} → ${res.lightmapUv.verticesAfter}${res.lightmapUv.lodPrimitives ? `; ${res.lightmapUv.lodPrimitives} LOD primitive(s) took level 0's layout by projection (${res.lightmapUv.lodVertices} vertices)` : ''}`)
-    if (res.lod) {
-      for (const t of res.lod.tris) log(`   lod: ${t.name} ${t.levels.join(' / ')} tris`)
-      for (const b of res.lod.bones) log(`   lod bones: ${b.name} last level ${b.before} → ${b.after} joints`)
-      for (const k of res.lod.skipped) log(`   lod: ${k.name} level ${k.level} dropped — the simplifier reached only ${k.tris} tris (seams / hard surfaces; try a smaller ratio)`)
-      if (!res.lod.nodes) log(`   lod: no mesh with >= 2000 triangles (or the _LOD nodes are already there)`)
-    }
-    const output = outputFor(input, oVal, files.length > 1, useKtx2)
-    // glTF's top-level `scene` is optional and glTF-Transform only writes it when set — strict
-    // loaders (OGL: `scenes[undefined]`) then load zero roots and draw nothing. Pin the first scene.
-    const root = doc.getRoot()
-    if (!root.getDefaultScene() && root.listScenes().length > 0) root.setDefaultScene(root.listScenes()[0])
-    await io.write(output, doc)
-    const beforeBytes = statSync(input).size
-    const after = readFileSync(output)
-    log(`💾 wrote ${output}  (${kb(beforeBytes)} → ${kb(after.byteLength)})`)
-    log(formatReport(validateGlb(after), output))
-  }
-  return exitCode
-}
-
-const cmdSky = async (p: Parsed): Promise<number> => {
-  const input = p.positionals[0]
-  if (!input) { console.error("✗ usage: lecodes-assets sky <env.exr|.hdr> [-o dir] [--size N]"); return 2 }
-  log(`
-🌤  ${input}`)
-  try {
-    const res = await buildSky(input, {
-      outDir: p.values.get("-o")?.[0],
-      size: num(p, "--size"),
-      iblSize: num(p, "--ibl-size"),
-      skyName: p.values.get("--name")?.[0],
-      iblName: p.values.get("--ibl-name")?.[0],
-      iblOnly: p.flags.has("--ibl-only"),
-      log,
-    })
-    log(formatSkyReport(res))
-    return 0
-  } catch (e) {
-    console.error(`✗ ${(e as Error).message}`)
-    return 1
-  }
-}
-
-const cmdTerrainPack = async (p: Parsed): Promise<number> => {
-  if (p.positionals.length === 0) { console.error("✗ usage: lecodes-assets terrain-pack <layer> [<layer> …] [-o dir] [--normals n0 n1 …] [--names a b …] [--size N] [--png] [--flip-y]"); return 2 }
-  const { resolveTerrainLayer, packTerrainTextures } = await import("./terrainPack")
-  const normals = p.values.get("--normals") ?? []
-  const names = p.values.get("--names") ?? []
-  const outDir = resolve(p.values.get("-o")?.[0] ?? "terrain")
-  try {
-    const layers = p.positionals.map((input, i) => {
-      const n = normals[i]
-      return resolveTerrainLayer(input, n && n !== "-" ? n : undefined, names[i])
-    })
-    log(`\n🏔  ${layers.length} layer(s) → ${outDir}`)
-    const res = await packTerrainTextures(layers, {
-      outDir, size: num(p, "--size"), png: p.flags.has("--png"), flipY: p.flags.has("--flip-y"),
-      quality: num(p, "--quality"), log,
-    })
-    log(`\n   Terrain.create({ …,\n${res.snippet.split("\n").map((l) => "     " + l).join("\n")}\n   })   (asset() paths relative to the calling file)`)
-    return 0
-  } catch (e) {
-    console.error(`✗ ${(e as Error).message}`)
-    return 1
-  }
-}
-
-const cmdUnreal = async (p: Parsed): Promise<number> => {
-  const [ sub, target ] = p.positionals
-  if (!target || (sub !== "ls" && sub !== "tex")) { log(USAGE); return 2 }
-  if (!existsSync(target)) { console.error(`✗ not found: ${target}`); return 1 }
-  if (sub === "ls") {
-    const { scanUnreal, formatUnrealListing } = await import("./unreal/list")
-    log(formatUnrealListing(target, scanUnreal(target), { all: p.flags.has("--all") }))
-    return 0
-  }
-  // `tex`: the source image out of a Texture2D asset, as stored (--raw) or ready for glTF
-  const { readPackageFile } = await import("./unreal/index")
-  const { extractTexture } = await import("./unreal/texture")
-  const img = await extractTexture(readPackageFile(target))
-  const t = img.texture
-  log(`🖼  ${t.name}: ${t.source.width}×${t.source.height} ${t.source.format} ${t.source.compression} · ${t.compressionSettings}${t.srgb ? " · sRGB" : ""}`)
-  let data = img.data, mime = img.mimeType
-  if (!p.flags.has("--raw") && img.swapRb) {
-    const { fixChannels } = await import("./unreal/materials")
-    const fixed = await fixChannels(data, mime, { swapRb: true, flipGreen: p.flags.has("--flip-green"), maxSize: num(p, "--max-size") ?? 0 })
-    data = fixed.data; mime = fixed.mimeType
-    log(`   red/blue swapped back (the source is ${t.source.format})${p.flags.has("--flip-green") ? " · normal green flipped" : ""}`)
-  }
-  const out = p.values.get("-o")?.[0] ?? target.replace(/\.uasset$/i, mime === "image/png" ? ".png" : ".jpg")
-  writeFileSync(out, data)
-  log(`💾 wrote ${out}  (${(data.byteLength / 1024).toFixed(0)} KB, ${mime})`)
-  return 0
-}
-
-export const runAssetsCli = async (argv: string[]): Promise<number> => {
-  const [ cmd, ...rest ] = argv
-  const p = parse(rest)
-  switch (cmd) {
-    case "convert": return cmdConvert(p)
-    case "probe": return cmdProbe(p)
-    case "unpack": return cmdUnpack(p)
-    case "doctor": return cmdDoctor(p)
-    case "retarget": return cmdRetarget(p)
-    case "marks": return cmdMarks(p)
-    case "avatar": return cmdAvatar(p)
-    case "mirror": return cmdMirror(p)
-    case "bvh": return cmdBvh(p)
-    case "sky": return cmdSky(p)
-    case "terrain-pack": return cmdTerrainPack(p)
-    case "scene": return cmdScene(p)
-    case "unreal": return cmdUnreal(p)
-    default: log(USAGE); return cmd ? 2 : 0
-  }
-}
-
-// Direct invocation (`bun src/cli.ts …` / the package bin) — `lecodes assets` imports runAssetsCli instead.
-const isMain = typeof process !== "undefined" && process.argv[1] !== undefined && /cli.(ts|js)$/.test(process.argv[1]) && !process.env.LECODES_ASSETS_NO_MAIN
-if (isMain) {
-  runAssetsCli(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(`✗ ${e?.message ?? e}`); process.exit(1) })
-}
+#!/usr/bin/env node
+// lecodes-assets — the LeCodes asset pipeline CLI (also reachable as `lecodes assets …`).
+//
+// A command is DATA (`src/commands/<name>.ts`, listed in `src/commands/index.ts`): its flags are
+// declared once, the argv is parsed against that declaration and every help page is rendered from
+// it (`src/cli-kit`). `lecodes assets` for the command list, `lecodes assets <command> --help` for one.
+
+import { runProgram } from "./cli-kit"
+import { program } from "./commands"
+
+/** Run one command line (the command first). Resolves to the exit code. */
+export const runAssetsCli = (argv: string[]): Promise<number> => runProgram(program, argv)
+
+/** The lightmap unwrap of whole GLB files, in place (src/unwrap) — what `lecodes lightmap bake` runs on the GLBs the app
+ *  references that have no TEXCOORD_1. Loaded on the first call, so the command line stays light. */
+export const unwrapGlbFiles = async (...args: Parameters<typeof import("./unwrap").unwrapGlbFiles>): ReturnType<typeof import("./unwrap").unwrapGlbFiles> =>
+  (await import("./unwrap")).unwrapGlbFiles(...args)
+export type { UnwrapFileOptions, UnwrapFileReport } from "./unwrap"
+
+// Direct invocation (`bun src/cli.ts …` / the package bin) — `lecodes assets` imports runAssetsCli instead.
+const isMain = typeof process !== "undefined" && process.argv[1] !== undefined && /cli.(ts|js)$/.test(process.argv[1]) && !process.env.LECODES_ASSETS_NO_MAIN
+if (isMain) {
+  runAssetsCli(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(`✗ ${e?.message ?? e}`); process.exit(1) })
+}