lecodes-assets 0.2.0 → 0.2.1

package/src/cli.ts

@@ -0,0 +1,1039 @@
+#!/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) })
+}