@series-inc/stowkit-cli 0.1.14 → 0.1.16

package/dist/asset-commands.d.ts

@@ -0,0 +1,4 @@
+export declare function renameAsset(projectDir: string, assetPath: string, newName: string): Promise<void>;
+export declare function moveAsset(projectDir: string, assetPath: string, targetFolder: string): Promise<void>;
+export declare function deleteAsset(projectDir: string, assetPath: string): Promise<void>;
+export declare function setStringId(projectDir: string, assetPath: string, newStringId: string): Promise<void>;

package/dist/asset-commands.js

@@ -0,0 +1,122 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectConfig, renameFile, deleteFile, readFile, } from './node-fs.js';
+import { readStowmeta, writeStowmeta, } from './app/stowmeta-io.js';
+// ─── Rename ──────────────────────────────────────────────────────────────────
+export async function renameAsset(projectDir, assetPath, newName) {
+    const config = await readProjectConfig(projectDir);
+    // Build new ID: same folder, new filename (preserve original extension)
+    const folder = assetPath.includes('/') ? assetPath.slice(0, assetPath.lastIndexOf('/') + 1) : '';
+    const oldBase = assetPath.split('/').pop() ?? assetPath;
+    const extMatch = oldBase.match(/\.[^.]+$/);
+    const ext = extMatch ? extMatch[0] : '';
+    const fullNewName = ext && !newName.endsWith(ext) ? newName + ext : newName;
+    const newId = folder + fullNewName;
+    if (newId === assetPath) {
+        console.log('Nothing to rename — same name.');
+        return;
+    }
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // Rename source, stowmeta, stowcache
+    await renameFile(config.srcArtDir, assetPath, newId);
+    await renameFile(config.srcArtDir, `${assetPath}.stowmeta`, `${newId}.stowmeta`);
+    await renameFile(config.srcArtDir, `${assetPath}.stowcache`, `${newId}.stowcache`);
+    // For GLB containers, rename the .children cache directory
+    const meta = await readStowmeta(config.srcArtDir, newId);
+    if (meta && meta.type === 'glbContainer') {
+        await renameFile(config.srcArtDir, `${assetPath}.children`, `${newId}.children`);
+    }
+    console.log(`Renamed: ${assetPath} → ${newId}`);
+}
+// ─── Move ────────────────────────────────────────────────────────────────────
+export async function moveAsset(projectDir, assetPath, targetFolder) {
+    const config = await readProjectConfig(projectDir);
+    const fileName = assetPath.split('/').pop() ?? assetPath;
+    const newId = targetFolder ? `${targetFolder}/${fileName}` : fileName;
+    if (newId === assetPath) {
+        console.log('Nothing to move — already in target folder.');
+        return;
+    }
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // Move source, stowmeta, stowcache
+    await renameFile(config.srcArtDir, assetPath, newId);
+    await renameFile(config.srcArtDir, `${assetPath}.stowmeta`, `${newId}.stowmeta`);
+    await renameFile(config.srcArtDir, `${assetPath}.stowcache`, `${newId}.stowcache`);
+    // For GLB containers, move the .children cache directory and update child references
+    const meta = await readStowmeta(config.srcArtDir, newId);
+    if (meta && meta.type === 'glbContainer') {
+        await renameFile(config.srcArtDir, `${assetPath}.children`, `${newId}.children`);
+        // Update texture references in material configs
+        const glbMeta = meta;
+        const oldPrefix = assetPath + '/';
+        const newPrefix = newId + '/';
+        let updated = false;
+        for (const child of glbMeta.children ?? []) {
+            if (child.materialConfig) {
+                for (const prop of child.materialConfig.properties) {
+                    if (prop.textureAsset?.startsWith(oldPrefix)) {
+                        prop.textureAsset = newPrefix + prop.textureAsset.slice(oldPrefix.length);
+                        updated = true;
+                    }
+                }
+            }
+            if (child.materialOverrides) {
+                for (const [k, v] of Object.entries(child.materialOverrides)) {
+                    if (v?.startsWith(oldPrefix)) {
+                        child.materialOverrides[k] = newPrefix + v.slice(oldPrefix.length);
+                        updated = true;
+                    }
+                }
+            }
+        }
+        if (updated) {
+            await writeStowmeta(config.srcArtDir, newId, glbMeta);
+        }
+    }
+    console.log(`Moved: ${assetPath} → ${newId}`);
+}
+// ─── Delete ──────────────────────────────────────────────────────────────────
+export async function deleteAsset(projectDir, assetPath) {
+    const config = await readProjectConfig(projectDir);
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // For GLB containers, also delete the .children cache directory
+    const meta = await readStowmeta(config.srcArtDir, assetPath);
+    if (meta && meta.type === 'glbContainer') {
+        const childrenDir = path.join(config.srcArtDir, `${assetPath}.children`);
+        await fs.rm(childrenDir, { recursive: true, force: true }).catch(() => { });
+    }
+    // Delete source, stowmeta, stowcache
+    await deleteFile(config.srcArtDir, assetPath);
+    await deleteFile(config.srcArtDir, `${assetPath}.stowmeta`);
+    await deleteFile(config.srcArtDir, `${assetPath}.stowcache`);
+    console.log(`Deleted: ${assetPath}`);
+}
+// ─── Set stringId ────────────────────────────────────────────────────────────
+export async function setStringId(projectDir, assetPath, newStringId) {
+    const config = await readProjectConfig(projectDir);
+    const meta = await readStowmeta(config.srcArtDir, assetPath);
+    if (!meta) {
+        console.error(`No .stowmeta found for: ${assetPath}`);
+        console.error('Run `stowkit build` or `stowkit scan` first to generate it.');
+        process.exit(1);
+    }
+    const oldStringId = meta.stringId;
+    meta.stringId = newStringId;
+    await writeStowmeta(config.srcArtDir, assetPath, meta);
+    console.log(`Updated stringId: "${oldStringId}" → "${newStringId}" (${assetPath})`);
+}

package/dist/cli.js

@@ -6,6 +6,8 @@ import { fullBuild, scanProject, showStatus } from './orchestrator.js';
 import { startServer } from './server.js';
 import { initProject } from './init.js';
 import { cleanupProject } from './cleanup.js';
+import { createMaterial } from './create-material.js';
+import { renameAsset, moveAsset, deleteAsset, setStringId } from './asset-commands.js';
 const args = process.argv.slice(2);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 function printUsage() {
@@ -17,6 +19,11 @@ Usage:
   stowkit process [dir]           Compress assets (respects cache)
   stowkit status [dir]            Show project summary, stale asset count
   stowkit clean [dir]             Delete orphaned .stowcache and .stowmeta files
+  stowkit create-material <path>  Create a .stowmat material file
+  stowkit rename <path> <name>    Rename an asset file
+  stowkit move <path> <folder>    Move an asset to a different folder
+  stowkit delete <path>           Delete an asset and its sidecar files
+  stowkit set-id <path> <id>      Change an asset's stringId
   stowkit packer [dir]            Open the packer GUI
   stowkit editor [dir]            Open the level editor
   stowkit serve [dir]             Start API server only (no GUI)
@@ -25,6 +32,7 @@ Options:
   --force       Ignore cache and reprocess everything
   --verbose     Detailed output
   --port        Server port (default 3210)
+  --schema      Material schema template: pbr (default), unlit, or custom name
   --help        Show this help message
 `.trim());
 }
@@ -94,6 +102,54 @@ async function main() {
             case 'clean':
                 await cleanupProject(projectDir, { verbose });
                 break;
+            case 'create-material': {
+                // For create-material, the positional arg is the material path, not project dir
+                const matPath = args.find(a => !a.startsWith('-') && a !== command);
+                if (!matPath) {
+                    console.error('Usage: stowkit create-material <path> [--schema pbr|unlit|<name>]');
+                    process.exit(1);
+                }
+                const schemaIdx = args.indexOf('--schema');
+                const schema = schemaIdx >= 0 ? args[schemaIdx + 1] : undefined;
+                await createMaterial('.', matPath, { schema });
+                break;
+            }
+            case 'rename': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit rename <asset-path> <new-name>');
+                    process.exit(1);
+                }
+                await renameAsset('.', positional[0], positional[1]);
+                break;
+            }
+            case 'move': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit move <asset-path> <target-folder>');
+                    process.exit(1);
+                }
+                await moveAsset('.', positional[0], positional[1]);
+                break;
+            }
+            case 'delete': {
+                const assetPath = args.find(a => !a.startsWith('-') && a !== command);
+                if (!assetPath) {
+                    console.error('Usage: stowkit delete <asset-path>');
+                    process.exit(1);
+                }
+                await deleteAsset('.', assetPath);
+                break;
+            }
+            case 'set-id': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit set-id <asset-path> <new-string-id>');
+                    process.exit(1);
+                }
+                await setStringId('.', positional[0], positional[1]);
+                break;
+            }
             case 'packer': {
                 const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
                 if (!packerDir) {

package/dist/create-material.d.ts

@@ -0,0 +1,3 @@
+export declare function createMaterial(projectDir: string, relativePath: string, opts?: {
+    schema?: string;
+}): Promise<void>;

package/dist/create-material.js

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectConfig } from './node-fs.js';
+const TEMPLATES = {
+    pbr: [
+        { fieldName: 'BaseColor', fieldType: 'texture', previewFlag: 'mainTex', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'Normal', fieldType: 'texture', previewFlag: 'none', value: [0, 0, 1, 0], textureAsset: null },
+        { fieldName: 'Tint', fieldType: 'color', previewFlag: 'tint', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'AlphaTest', fieldType: 'float', previewFlag: 'alphaTest', value: [0.5, 0, 0, 0], textureAsset: null },
+    ],
+    unlit: [
+        { fieldName: 'BaseColor', fieldType: 'texture', previewFlag: 'mainTex', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'Tint', fieldType: 'color', previewFlag: 'tint', value: [1, 1, 1, 1], textureAsset: null },
+    ],
+};
+export async function createMaterial(projectDir, relativePath, opts) {
+    const config = await readProjectConfig(projectDir);
+    // Ensure .stowmat extension
+    if (!relativePath.endsWith('.stowmat')) {
+        relativePath += '.stowmat';
+    }
+    const fullPath = path.join(config.srcArtDir, relativePath);
+    // Don't overwrite existing
+    try {
+        await fs.access(fullPath);
+        console.error(`Material already exists: ${relativePath}`);
+        process.exit(1);
+    }
+    catch {
+        // Does not exist — good
+    }
+    const schemaName = opts?.schema ?? 'pbr';
+    const properties = TEMPLATES[schemaName] ?? [];
+    const mat = {
+        version: 1,
+        schemaName,
+        properties,
+    };
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, JSON.stringify(mat, null, 2) + '\n');
+    console.log(`Created material: ${relativePath}`);
+    console.log(`  Schema: ${schemaName}`);
+    console.log(`  Properties: ${properties.map(p => p.fieldName).join(', ') || '(none)'}`);
+    if (!TEMPLATES[schemaName]) {
+        console.log(`  (Custom schema — no template properties. Edit the file to add properties.)`);
+    }
+}

package/dist/orchestrator.js

@@ -98,58 +98,8 @@ export async function fullBuild(projectDir, opts) {
         }
         assets.push(asset);
         assetsById.set(id, asset);
-        // Expand GlbContainer children
-        if (type === AssetType.GlbContainer && meta.type === 'glbContainer') {
-            const glbMeta = meta;
-            if (glbMeta.children && glbMeta.children.length > 0) {
-                asset.status = 'ready'; // Container itself is always "ready"
-                for (const child of glbMeta.children) {
-                    const childId = `${id}/${child.name}`;
-                    const baseName = child.name.replace(/\.[^.]+$/, '');
-                    // Read settings from inline child entry
-                    const { type: cType, settings: cSettings } = glbChildToAssetSettings(child);
-                    const childAsset = {
-                        id: childId,
-                        fileName: child.name,
-                        stringId: child.stringId || baseName,
-                        type: cType,
-                        status: 'pending',
-                        settings: cSettings,
-                        sourceSize: 0,
-                        processedSize: 0,
-                        parentId: id,
-                        locked: true,
-                    };
-                    // Check cache
-                    if (!force && child.cache) {
-                        const cached = await readCacheBlobs(config.srcArtDir, childId);
-                        if (cached) {
-                            for (const [key, data] of cached) {
-                                if (key === `${childId}:__metadata__`) {
-                                    try {
-                                        childAsset.metadata = JSON.parse(new TextDecoder().decode(data));
-                                    }
-                                    catch { /* skip */ }
-                                }
-                                else {
-                                    BlobStore.setProcessed(key, data);
-                                }
-                            }
-                            childAsset.status = 'ready';
-                            childAsset.processedSize = BlobStore.getProcessed(childId)?.length ?? 0;
-                            if (verbose)
-                                console.log(`  [cached] ${childId}`);
-                        }
-                    }
-                    assets.push(childAsset);
-                    assetsById.set(childId, childAsset);
-                }
-            }
-            else {
-                // No children manifest yet — need to parse GLB to discover them
-                // This will be handled during processing
-            }
-        }
+        // GlbContainers are always extracted in section 2b (even if children exist in manifest)
+        // so that preserveHierarchy changes, re-exports, etc. are always reflected.
     }
     // Materials from .stowmat files
     for (const matFile of scan.matFiles) {
@@ -178,10 +128,9 @@ export async function fullBuild(projectDir, opts) {
         assets.push(asset);
         assetsById.set(id, asset);
     }
-    // 2b. Process GLB containers that need extraction (no children yet)
-    // Store extract results so mesh/animation children can be processed after encoder init
+    // 2b. Extract all GLB containers (always re-parse so preserveHierarchy etc. are reflected)
     const glbExtracts = new Map();
-    const glbContainers = assets.filter(a => a.type === AssetType.GlbContainer && a.status === 'pending');
+    const glbContainers = assets.filter(a => a.type === AssetType.GlbContainer);
     for (const container of glbContainers) {
         try {
             const sourceData = await readFile(config.srcArtDir, container.id);
@@ -237,8 +186,6 @@ export async function fullBuild(projectDir, opts) {
             // Create child assets from inline entries
             for (const child of childrenManifest) {
                 const childId = `${container.id}/${child.name}`;
-                if (assetsById.has(childId))
-                    continue;
                 const baseName = child.name.replace(/\.[^.]+$/, '');
                 const { type: cType, settings: cSettings } = glbChildToAssetSettings(child);
                 const childAsset = {
@@ -274,6 +221,27 @@ export async function fullBuild(projectDir, opts) {
                         childAsset.processedSize = result.processedSize;
                     }
                 }
+                // Check cache for texture/mesh children (skip if --force)
+                if (childAsset.status === 'pending' && !force && child.cache) {
+                    const cached = await readCacheBlobs(config.srcArtDir, childId);
+                    if (cached) {
+                        for (const [key, data] of cached) {
+                            if (key === `${childId}:__metadata__`) {
+                                try {
+                                    childAsset.metadata = JSON.parse(new TextDecoder().decode(data));
+                                }
+                                catch { /* skip */ }
+                            }
+                            else {
+                                BlobStore.setProcessed(key, data);
+                            }
+                        }
+                        childAsset.status = 'ready';
+                        childAsset.processedSize = BlobStore.getProcessed(childId)?.length ?? 0;
+                        if (verbose)
+                            console.log(`  [cached] ${childId}`);
+                    }
+                }
                 assets.push(childAsset);
                 assetsById.set(childId, childAsset);
             }
@@ -318,10 +286,9 @@ export async function fullBuild(projectDir, opts) {
             console.error(`  [glb] ${container.id} FAILED: ${container.error}`);
         }
     }
-    // 2c. Process GLB mesh children + stale assets via worker pool
-    const glbMeshChildren = assets.filter(a => a.status === 'pending' && a.parentId && (a.type === AssetType.StaticMesh || a.type === AssetType.SkinnedMesh));
-    const pending = assets.filter(a => a.status === 'pending' && !a.parentId);
-    const totalWork = glbMeshChildren.length + pending.length;
+    // 2c. Process all pending assets via worker pool (one queue, no split)
+    const pending = assets.filter(a => a.status === 'pending');
+    const totalWork = pending.length;
     if (totalWork === 0) {
         if (verbose)
             console.log('All assets cached, nothing to process.');
@@ -330,39 +297,34 @@ export async function fullBuild(projectDir, opts) {
         console.log(`Processing ${totalWork} asset(s)...`);
         const pool = new WorkerPool({ wasmDir: opts?.wasmDir });
         let processed = 0;
-        // Process GLB mesh children
-        for (const child of glbMeshChildren) {
-            const extract = glbExtracts.get(child.parentId);
-            if (!extract)
-                continue;
-            const mesh = extract.meshes.find(m => `${child.parentId}/${m.name}` === child.id);
-            if (!mesh)
-                continue;
-            try {
-                const { result, blobs } = await pool.processExtractedMesh({ childId: child.id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: child.stringId, settings: child.settings });
-                for (const [key, data] of blobs)
-                    BlobStore.setProcessed(key, data);
-                child.status = 'ready';
-                child.metadata = result.metadata;
-                child.processedSize = result.processedSize;
-                processed++;
-                if (verbose)
-                    console.log(`  [${processed}/${totalWork}] ${child.id} (glb-mesh)`);
-            }
-            catch (err) {
-                child.status = 'error';
-                child.error = err instanceof Error ? err.message : String(err);
-                processed++;
-            }
-        }
-        // Process remaining pending assets with concurrency limit
         const queue = [...pending];
         async function processNext() {
             while (queue.length > 0) {
                 const asset = queue.shift();
                 const id = asset.id;
                 try {
-                    // Load source (GLB texture children have source in BlobStore already)
+                    // GLB mesh children use processExtractedMesh (needs parsed mesh data)
+                    const isMeshChild = asset.parentId &&
+                        (asset.type === AssetType.StaticMesh || asset.type === AssetType.SkinnedMesh);
+                    if (isMeshChild) {
+                        const extract = glbExtracts.get(asset.parentId);
+                        if (!extract)
+                            throw new Error(`No extract for parent ${asset.parentId}`);
+                        const mesh = extract.meshes.find(m => `${asset.parentId}/${m.name}` === id);
+                        if (!mesh)
+                            throw new Error(`Mesh not found in extract: ${id}`);
+                        const { result, blobs } = await pool.processExtractedMesh({ childId: id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: asset.stringId, settings: asset.settings });
+                        for (const [key, data] of blobs)
+                            BlobStore.setProcessed(key, data);
+                        asset.status = 'ready';
+                        asset.metadata = result.metadata;
+                        asset.processedSize = result.processedSize;
+                        processed++;
+                        if (verbose)
+                            console.log(`  [${processed}/${totalWork}] ${id} (glb-mesh)`);
+                        continue;
+                    }
+                    // Everything else uses processAsset (source bytes)
                     let sourceData = BlobStore.getSource(id);
                     if (!sourceData) {
                         const data = await readFile(config.srcArtDir, id);
@@ -381,39 +343,39 @@ export async function fullBuild(projectDir, opts) {
                     asset.processedSize = result.processedSize;
                     processed++;
                     console.log(`  [${processed}/${totalWork}] ${id} (${elapsed}ms)`);
-                    // Write cache
-                    const cacheEntries = new Map();
-                    const processedBlob = BlobStore.getProcessed(id);
-                    if (processedBlob)
-                        cacheEntries.set(id, processedBlob);
-                    if (result.metadata) {
-                        cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(result.metadata)));
-                    }
-                    // Auxiliary blobs
-                    for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
-                        const blob = BlobStore.getProcessed(`${id}${suffix}`);
-                        if (blob)
-                            cacheEntries.set(`${id}${suffix}`, blob);
-                    }
-                    const animCountBlob = BlobStore.getProcessed(`${id}:animCount`);
-                    const clipCount = animCountBlob ? animCountBlob[0] : 0;
-                    for (let ci = 0; ci < clipCount; ci++) {
-                        const animData = BlobStore.getProcessed(`${id}:anim:${ci}`);
-                        if (animData)
-                            cacheEntries.set(`${id}:anim:${ci}`, animData);
-                        const animMeta = BlobStore.getProcessed(`${id}:animMeta:${ci}`);
-                        if (animMeta)
-                            cacheEntries.set(`${id}:animMeta:${ci}`, animMeta);
-                    }
-                    if (cacheEntries.size > 0) {
-                        await writeCacheBlobs(config.srcArtDir, id, cacheEntries);
-                        // Stamp cache in .stowmeta
-                        const snapshot = await getFileSnapshot(config.srcArtDir, id);
-                        if (snapshot) {
-                            const meta = await readStowmeta(config.srcArtDir, id);
-                            if (meta) {
-                                meta.cache = buildCacheStamp(snapshot, asset.type, asset.settings);
-                                await writeStowmeta(config.srcArtDir, id, meta);
+                    // Write cache (only for top-level assets that have their own file on disk)
+                    if (!asset.parentId) {
+                        const cacheEntries = new Map();
+                        const processedBlob = BlobStore.getProcessed(id);
+                        if (processedBlob)
+                            cacheEntries.set(id, processedBlob);
+                        if (result.metadata) {
+                            cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(result.metadata)));
+                        }
+                        for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+                            const blob = BlobStore.getProcessed(`${id}${suffix}`);
+                            if (blob)
+                                cacheEntries.set(`${id}${suffix}`, blob);
+                        }
+                        const animCountBlob = BlobStore.getProcessed(`${id}:animCount`);
+                        const clipCount = animCountBlob ? animCountBlob[0] : 0;
+                        for (let ci = 0; ci < clipCount; ci++) {
+                            const animData = BlobStore.getProcessed(`${id}:anim:${ci}`);
+                            if (animData)
+                                cacheEntries.set(`${id}:anim:${ci}`, animData);
+                            const animMeta = BlobStore.getProcessed(`${id}:animMeta:${ci}`);
+                            if (animMeta)
+                                cacheEntries.set(`${id}:animMeta:${ci}`, animMeta);
+                        }
+                        if (cacheEntries.size > 0) {
+                            await writeCacheBlobs(config.srcArtDir, id, cacheEntries);
+                            const snapshot = await getFileSnapshot(config.srcArtDir, id);
+                            if (snapshot) {
+                                const meta = await readStowmeta(config.srcArtDir, id);
+                                if (meta) {
+                                    meta.cache = buildCacheStamp(snapshot, asset.type, asset.settings);
+                                    await writeStowmeta(config.srcArtDir, id, meta);
+                                }
                             }
                         }
                     }
@@ -427,7 +389,7 @@ export async function fullBuild(projectDir, opts) {
             }
         }
         const workers = [];
-        for (let i = 0; i < Math.min(maxConcurrent, pending.length); i++) {
+        for (let i = 0; i < Math.min(maxConcurrent, queue.length); i++) {
             workers.push(processNext());
         }
         await Promise.all(workers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,7 +17,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.7",
+    "@series-inc/stowkit-packer-gui": "^0.1.9",
     "@series-inc/stowkit-editor": "^0.1.2",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",

package/skill.md

@@ -2,6 +2,18 @@
 
 StowKit is a game asset pipeline that compresses and packs assets into `.stow` binary files for runtime loading.
 
+## CRITICAL: Never manually create .stowmeta files
+
+`.stowmeta` files are **auto-generated by the CLI**. To add any asset to the project:
+
+1. Place the source file (GLB, PNG, FBX, WAV, etc.) into the `srcArtDir`
+2. Run `npx stowkit build` (or `npx stowkit scan`)
+3. The CLI detects the new file, generates the correct `.stowmeta` with proper defaults, and processes it
+
+**Do not write `.stowmeta` files by hand.** Only edit an existing `.stowmeta` after it has been generated by the CLI (e.g. to change quality settings, pack assignment, or stringId). The same applies to GLB children — the `children` array is populated automatically on the first build.
+
+To create materials, use `npx stowkit create-material <path>` — this scaffolds a `.stowmat` file with the right structure. You can also create `.stowmat` files manually if needed.
+
 ## Project Structure
 
 A StowKit project has a `.felicityproject` JSON file at its root:
@@ -30,6 +42,11 @@ npx stowkit scan [dir]              # Detect new assets and generate .stowmeta d
 npx stowkit process [dir]           # Compress assets (respects cache)
 npx stowkit status [dir]            # Show project summary, stale asset count
 npx stowkit clean [dir]             # Delete orphaned .stowcache and .stowmeta files
+npx stowkit create-material <path>  # Create a .stowmat material file (--schema pbr|unlit|<name>)
+npx stowkit rename <path> <name>    # Rename an asset file (preserves extension, updates sidecars)
+npx stowkit move <path> <folder>    # Move an asset to a different folder (updates GLB child refs)
+npx stowkit delete <path>           # Delete an asset and its .stowmeta/.stowcache files
+npx stowkit set-id <path> <id>      # Change an asset's stringId
 npx stowkit packer [dir]            # Open the packer GUI in browser
 npx stowkit editor [dir]            # Open the level editor in browser
 npx stowkit serve [dir]             # Start API server only (no GUI)
@@ -41,6 +58,7 @@ All commands default to the current directory.
 - `--force` — Ignore cache and reprocess everything
 - `--verbose` / `-v` — Detailed output
 - `--port <number>` — Server port (default 3210)
+- `--schema <name>` — Material schema template for `create-material` (default: `pbr`)
 
 ## Supported Asset Types
 
@@ -56,9 +74,9 @@ All commands default to the current directory.
 
 **GLB/GLTF is the recommended format for 3D models.** Dropping a `.glb` file into the project is the easiest way to get meshes, textures, materials, and animations into the pipeline — everything is extracted and processed automatically. FBX and OBJ are still supported as standalone mesh formats but lack the automatic material/texture extraction that GLB provides.
 
-## .stowmeta Files
+## .stowmeta Files (auto-generated — do not create manually)
 
-Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings.
+Every source asset gets a `.stowmeta` sidecar file generated by `npx stowkit build` or `npx stowkit scan`. These files control processing settings and should only be **edited** (never created) by hand. The examples below are reference for understanding and editing existing files.
 
 **Texture example:**
 ```json
@@ -347,6 +365,18 @@ Add `*.stowcache` to `.gitignore`.
 5. To exclude a child from packing, set `"excluded": true` on that child entry
 6. To preserve the scene graph hierarchy in static meshes, set `"preserveHierarchy": true` on the container
 
+### Enabling preserveHierarchy from CLI
+
+To enable hierarchy preservation on a GLB, edit its `.stowmeta` and set `"preserveHierarchy": true`, then rebuild:
+
+```bash
+# After the first build has generated the .stowmeta, edit it:
+# Set "preserveHierarchy": true in assets/models/hero.glb.stowmeta
+npx stowkit build
+```
+
+The CLI always re-extracts GLB containers on every build, so changes to `preserveHierarchy` take effect immediately — no `--force` needed.
+
 ### When to use preserveHierarchy
 
 - **Default (false):** All mesh geometry is baked to world space and flattened into a single mesh. Use this for simple props and environment pieces.
@@ -355,10 +385,17 @@ Add `*.stowcache` to `.gitignore`.
 
 ### Other common tasks
 
-- **Add a texture:** Drop a PNG/JPG into `assets/`, run `npx stowkit scan` to generate its `.stowmeta`, optionally edit settings, then `npx stowkit build`
-- **Change compression quality:** Edit the `.stowmeta` file's quality/resize fields, then `npx stowkit build`
-- **Create a material:** Create a `.stowmat` JSON file in `assets/`, run `npx stowkit scan`
-- **Assign material to mesh:** Edit the mesh's `.stowmeta` to add `materialOverrides`
+- **Add a texture:** Place PNG/JPG into `assets/`, run `npx stowkit build`. The CLI auto-generates the `.stowmeta`. Do NOT create it yourself.
+- **Add audio:** Place WAV/MP3/OGG into `assets/`, run `npx stowkit build`. Same rule — never manually create `.stowmeta`.
+- **Add an FBX mesh:** Place FBX into `assets/`, run `npx stowkit build`.
+- **Enable preserve hierarchy on a GLB:** Edit the `.stowmeta` for the GLB container, set `"preserveHierarchy": true`, then `npx stowkit build`
+- **Change compression quality:** Edit the **existing** `.stowmeta` file's quality/resize fields (after it was generated by a build/scan), then `npx stowkit build`
+- **Create a material:** Run `npx stowkit create-material materials/MyMat` (creates `assets/materials/MyMat.stowmat` with PBR template). Use `--schema unlit` for unlit materials, or `--schema <name>` for a custom schema. Then run `npx stowkit build`.
+- **Assign material to mesh:** Edit the mesh's **existing** `.stowmeta` to add `materialOverrides`
+- **Rename an asset:** `npx stowkit rename textures/old_name.png new_name` (extension preserved automatically, sidecars renamed too)
+- **Move an asset:** `npx stowkit move textures/hero.png characters` (moves to `characters/hero.png`, updates GLB child refs if container)
+- **Delete an asset:** `npx stowkit delete textures/unused.png` (removes source + .stowmeta + .stowcache, cascades for GLB containers)
+- **Change an asset's stringId:** `npx stowkit set-id textures/hero.png hero_diffuse`
 - **Check project health:** Run `npx stowkit status`
 - **Full rebuild:** `npx stowkit build --force`
 - **Clean orphaned files:** `npx stowkit clean`