@playcraft/cli 0.1.68 → 0.1.70

package/dist/workspace-runtime/workspaces/archive.js

@@ -1,13 +1,21 @@
 import { constants } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { lstat, open, opendir, realpath } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createDeflateRaw } from 'node:zlib';
 import { isCredentialFile } from './git.js';
-const EXCLUDED_NAMES = new Set(['.git', 'node_modules', '.playcraft.json', '.playcraft-workspace.json']);
+import { verifyWorkspaceAssetProvenance, WORKSPACE_ASSET_PROVENANCE_PATH } from '../../asset-library/provenance.js';
+import { workspaceAssetProvenanceDocumentSchema } from '@playcraft/common/cloud-workspace/runtime';
+const EXCLUDED_NAMES = new Set(['.git', 'node_modules', '.playcraft-temp', '.playcraft.json', '.playcraft-workspace.json']);
 const MAX_SOURCE_BYTES = 2 * 1024 * 1024 * 1024;
 const MAX_ENTRIES = 50_000;
+const PUBLIC_ARCHIVE_ERRORS = new Set(['workspace_archive_changed', 'workspace_archive_too_large', 'workspace_archive_invalid_path',
+    'workspace_archive_failed', 'asset_provenance_authority_required', 'asset_provenance_authority_unavailable',
+    'asset_provenance_authority_mismatch', 'asset_provenance_authority_response_bound', 'asset_provenance_model_changed',
+    'asset_provenance_license_changed', 'asset_provenance_record_missing', 'asset_provenance_license_path_mismatch',
+    'asset_provenance_too_large', 'asset_provenance_changed', 'asset_provenance_notice_conflict', 'asset_provenance_expected_path_invalid']);
 const UTF8_DESCRIPTOR_FLAGS = 0x0808;
 const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
     let crc = value;
@@ -18,6 +26,13 @@ const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
 /** Exports working files, including ignored deliverables, without following symbolic links. */
 export async function createWorkspaceArchive(root, options = {}) {
     const rootReal = await realpath(root);
+    const provenance = await verifyWorkspaceAssetProvenance(rootReal, { verify: options.verifyProvenance,
+        expectedModelPaths: options.expectedModelPaths });
+    const expectedHashes = new Map();
+    for (const asset of provenance?.assets ?? []) {
+        expectedHashes.set(asset.path, asset.provenance.modelSha256);
+        expectedHashes.set(asset.licensePath, createHash('sha256').update(asset.provenance.licenseText).digest('hex'));
+    }
     const excludedRoots = await Promise.all((options.excludedRoots ?? []).map(path => realpath(path).catch(() => path)));
     const entries = [];
     let bytes = 0;
@@ -52,7 +67,8 @@ export async function createWorkspaceArchive(root, options = {}) {
             bytes += info.size;
             if (bytes > (options.maxSourceBytes ?? MAX_SOURCE_BYTES) || entries.length >= (options.maxEntries ?? MAX_ENTRIES))
                 throw new Error('workspace_archive_too_large');
-            entries.push({ path, target, info });
+            entries.push({ path, target, info, expectedHash: expectedHashes.get(path),
+                ...(path === WORKSPACE_ASSET_PROVENANCE_PATH && provenance ? { expectedProvenance: JSON.stringify(provenance) } : {}) });
         }
     };
     await walk(rootReal);
@@ -89,6 +105,8 @@ async function* zipFiles(root, entries, signal) {
             let crc = 0xffffffff;
             let size = 0;
             let compressedSize = 0;
+            const hash = entry.expectedHash ? createHash('sha256') : undefined;
+            const sourceChunks = [];
             const checksum = new Transform({ transform(chunk, _encoding, done) {
                     size += chunk.length;
                     if (size > info.size) {
@@ -97,6 +115,9 @@ async function* zipFiles(root, entries, signal) {
                     }
                     for (const byte of chunk)
                         crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+                    hash?.update(chunk);
+                    if (entry.expectedProvenance)
+                        sourceChunks.push(chunk);
                     done(null, chunk);
                 } });
             const compressed = createDeflateRaw();
@@ -118,6 +139,10 @@ async function* zipFiles(root, entries, signal) {
             }
             if (size !== info.size)
                 throw new Error('workspace_archive_changed');
+            if (hash && hash.digest('hex') !== entry.expectedHash)
+                throw new Error('asset_provenance_model_changed');
+            if (entry.expectedProvenance && JSON.stringify(workspaceAssetProvenanceDocumentSchema.parse(JSON.parse(Buffer.concat(sourceChunks).toString('utf8')))) !== entry.expectedProvenance)
+                throw new Error('asset_provenance_changed');
             const after = await handle.stat();
             if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs)
                 throw new Error('workspace_archive_changed');
@@ -188,7 +213,7 @@ export async function serveWorkspaceArchive(root, request, response, options = {
         else if (!controller.signal.aborted) {
             const reason = error instanceof Error ? error.message : 'workspace_archive_failed';
             response.writeHead(reason === 'workspace_archive_too_large' ? 413 : 409, { 'content-type': 'application/json', 'cache-control': 'private, no-store' });
-            response.end(JSON.stringify({ error: reason.startsWith('workspace_archive_') ? reason : 'workspace_archive_failed' }));
+            response.end(JSON.stringify({ error: PUBLIC_ARCHIVE_ERRORS.has(reason) ? reason : 'workspace_archive_failed' }));
         }
     }
     finally {

package/dist/workspace-runtime/workspaces/asset-library-import.js

@@ -6,6 +6,7 @@ import { BINARY_WORKSPACE_FILE_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES
 import { observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from './binary-write.js';
 import { shareWorkspaceAssetDirectory } from './asset-publication-access.js';
 import { ensureSharedDirectory } from './shared-write.js';
+import { publishLibraryModels } from '../../asset-library/provenance.js';
 import { isEditableAudioLibraryAsset, prepareAudioLibraryImport } from './audio-assets/library-import.js';
 import { readAudioArtifactPackage } from './audio-assets/artifact-package.js';
 const RESERVED = new Set(['.git', 'node_modules', '.playcraft-temp', '.tmp']);
@@ -341,6 +342,8 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
     await createPublicDirectory(rootReal, payload.targetDirectory);
     const result = { paths: [], skippedPaths: [], failures: [...transport.failures] };
     const processed = new Set(transport.failures.map(failure => failure.assetId));
+    const curated = [];
+    const plannedTargets = new Set();
     const progress = () => options.onProgress?.({ ...result, failures: [...result.failures,
             ...payload.assetIds.filter(id => !processed.has(id)).map(assetId => ({ assetId, error: 'asset_library_import_interrupted' }))] });
     await progress();
@@ -361,7 +364,7 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
             let name = originalName;
             let target = validPath([payload.targetDirectory, name].filter(Boolean).join('/'));
             let existing = await statTarget(rootReal, target);
-            if (existing && payload.collision === 'skip') {
+            if ((existing || plannedTargets.has(target)) && payload.collision === 'skip') {
                 result.skippedPaths.push(target);
                 processed.add(assetId);
                 await progress();
@@ -370,7 +373,7 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
             if (payload.collision === 'rename') {
                 const extension = asset.kind === 'bundle' ? '' : extname(originalName);
                 const stem = originalName.slice(0, originalName.length - extension.length);
-                for (let suffix = 1; existing; suffix++) {
+                for (let suffix = 1; existing || plannedTargets.has(target); suffix++) {
                     if (suffix > 10_000)
                         throw new AssetLibraryImportError('content_conflict');
                     name = `${stem} (${suffix})${extension}`;
@@ -378,6 +381,14 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
                     existing = await statTarget(rootReal, target);
                 }
             }
+            if (asset.provenance) {
+                const observed = existing ? await observeWorkspaceBinaryFile(rootReal, target) : undefined;
+                curated.push({ assetId, path: target, bytes: Buffer.from(asset.files[0].content, 'base64'),
+                    provenance: asset.provenance, expectedContentHash: observed?.contentHash ?? null });
+                plannedTargets.add(target);
+                await progress();
+                continue;
+            }
             if (asset.kind === 'bundle') {
                 const audio = isEditableAudioLibraryAsset(asset) ? await prepareAudioLibraryImport(rootReal, target, asset, assertCurrent) : undefined;
                 const incoming = audio?.asset ?? asset;
@@ -396,6 +407,8 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
             }
         }
         catch (error) {
+            if (error instanceof Error && ['stale_lease', 'batch_workspace_readonly'].includes(error.message))
+                throw error;
             const code = error instanceof AssetLibraryImportError ? error.message
                 : error instanceof Error && ['invalid_audio_library_package', 'audio_library_engine_unavailable', 'audio_library_source_unverified', 'audio_representation_conflict'].includes(error.message) ? error.message
                     : error?.code === 'content_conflict' ? 'content_conflict'
@@ -408,5 +421,23 @@ export async function importWorkspaceLibraryAssets(root, selection, snapshot, as
         if (publishedTransaction)
             await removeTransaction(rootReal, publishedTransaction).catch(() => undefined);
     }
+    if (curated.length) {
+        try {
+            const receipt = await publishLibraryModels(rootReal, curated, { operationId: options.operationId,
+                scope: options.scope, assertCurrent });
+            result.bundleReceipt = receipt;
+            result.paths.push(...receipt.files.map(file => file.path));
+        }
+        catch (error) {
+            if (error instanceof Error && ['stale_lease', 'batch_workspace_readonly'].includes(error.message))
+                throw error;
+            const code = error.code ?? (error instanceof Error ? error.message : 'asset_library_import_failed');
+            for (const model of curated)
+                result.failures.push({ assetId: model.assetId, error: code.slice(0, 256) });
+        }
+        for (const model of curated)
+            processed.add(model.assetId);
+        await progress();
+    }
     return workspaceAssetLibraryImportResultSchema.parse(result);
 }

package/dist/workspace-runtime/workspaces/asset-provenance-verifier.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assetLibraryModelProvenanceSchema, canonicalAssetLibraryModelProvenance } from '@playcraft/common/cloud-workspace/runtime';
+import { businessEndpoint } from '../../utils/environment-endpoints.js';
+import { ensureCliCredentials } from './cli-credentials.js';
+/** Compare the portable source record with the current user's immutable server revision. */
+export async function verifyRuntimeAssetProvenance(state, provenance) {
+    await ensureCliCredentials(state);
+    const credential = JSON.parse(await readFile(join(state.config.workspaceRoot, '.playcraft.json'), 'utf8'));
+    if (typeof credential.apiUrl !== 'string' || typeof credential.token !== 'string' || !credential.token)
+        throw new Error('asset_provenance_authority_unavailable');
+    const url = businessEndpoint(credential.apiUrl, `/api/agent/tools/asset-library/${encodeURIComponent(provenance.assetId)}`);
+    url.searchParams.set('revisionId', provenance.revisionId);
+    const response = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(15_000),
+        headers: { 'X-Sandbox-Token': credential.token, 'playcraft-env': state.config.environment } });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error('asset_provenance_authority_unavailable');
+    }
+    const maximum = 256 * 1024, chunks = [];
+    let length = 0;
+    if (!response.body)
+        throw new Error('asset_provenance_authority_unavailable');
+    for await (const chunk of response.body) {
+        length += chunk.byteLength;
+        if (length > maximum) {
+            await response.body.cancel().catch(() => undefined);
+            throw new Error('asset_provenance_authority_response_bound');
+        }
+        chunks.push(chunk);
+    }
+    const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    const authoritative = assetLibraryModelProvenanceSchema.parse(result.provenance);
+    if (canonicalAssetLibraryModelProvenance(authoritative) !== canonicalAssetLibraryModelProvenance(provenance))
+        throw new Error('asset_provenance_authority_mismatch');
+}

package/dist/workspace-runtime/workspaces/registry.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, realpath, rm } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 import { promisify } from 'node:util';
 import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, batchSourceSnapshotSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -10,6 +10,7 @@ import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
 import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
 import { writeWorkspaceCliContext } from './cli-context.js';
 import { attachWorkspaceRemote } from './git.js';
+import { markRemoteAttachPending } from './remote-attach-marker.js';
 import { ensureWorkspaceArtifactInstructions } from './instructions.js';
 import { repairWorkspaceShares } from './workspace-shares.js';
 export { WorkspaceContextError } from './context-error.js';
@@ -183,10 +184,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
             && (needsRemote || remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
             if (preparation?.mode !== 'clone' || !state.gitCredentials)
                 throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-            // private
-            await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
-            // private
-            await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
+            await markRemoteAttachPending(state, binding.workspaceId, binding.repositoryUrl, binding.branchName);
             // The credential helper only serves a workspace the journal knows to be bound.
             await state.journal.putWorkspace({ ...binding, directories });
             try {

package/dist/workspace-runtime/workspaces/remix-references.js

@@ -115,12 +115,18 @@ function validateRecord(record, directoryName) {
         originalFiles.reduce((sum, file) => sum + file.size, 0) > WORKSPACE_REMIX_REFERENCE_MAX_BYTES)
         throw new RemixReferenceError('remix_reference_manifest_invalid');
 }
-async function verifyReference(root, record, directoryName) {
+async function verifyReferenceMetadata(root, record, directoryName, alternateDirectory) {
     validateRecord(record, directoryName);
     const target = await safeDirectory(root, record.path);
     const receipt = JSON.parse((await readFileSafely(target, RECEIPT, MANIFEST_MAX_BYTES)).toString('utf8'));
-    if (JSON.stringify(workspaceRemixReferenceSchema.parse(receipt)) !== JSON.stringify(record))
+    const parsedReceipt = workspaceRemixReferenceSchema.parse(receipt);
+    if (JSON.stringify(parsedReceipt) !== JSON.stringify(record)
+        && (!alternateDirectory || JSON.stringify(parsedReceipt) !== JSON.stringify({ ...record, directoryName: alternateDirectory })))
         throw new RemixReferenceError('remix_reference_changed');
+    return target;
+}
+async function verifyReference(root, record, directoryName, alternateDirectory) {
+    const target = await verifyReferenceMetadata(root, record, directoryName, alternateDirectory);
     if ((await readFileSafely(target, ATTRIBUTES, 256)).toString('utf8') !== SNAPSHOT_ATTRIBUTES)
         throw new RemixReferenceError('remix_reference_changed');
     const expected = new Set([RECEIPT, ATTRIBUTES, ...record.files.map(file => file.path)]);
@@ -144,6 +150,117 @@ async function verifyReference(root, record, directoryName) {
             throw new RemixReferenceError('remix_reference_changed');
     }
 }
+/** Metadata-verified records identify files excluded by the batch source safety policy. */
+export async function batchReferenceMetadata(root) {
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return [];
+    }
+    const verified = [];
+    for (const record of items) {
+        try {
+            await verifyReferenceMetadata(root, record, record.directoryName);
+            verified.push(record);
+        }
+        catch { /* An unrelated invalid reference cannot block source capture. */ }
+    }
+    return verified;
+}
+/** Only verified imported snapshots can retain credential-free .env examples in a batch freeze. */
+export async function batchReferenceEnvExamples(root) {
+    const examples = new Set();
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return examples;
+    }
+    for (const record of items) {
+        const files = record.files.filter(file => /^\.env\.(?:example|sample|template)$/i.test(file.path.split('/').pop() ?? '')
+            && !isCredentialFile(file.sourcePath));
+        if (!files.length)
+            continue;
+        try {
+            await verifyReference(root, record, record.directoryName);
+            for (const file of files)
+                examples.add(`${record.path}/${file.path}`);
+        }
+        catch { /* An unselected damaged reference must not stop freezing the project. */ }
+    }
+    return examples;
+}
+/** Rebind frozen source references inside a member checkout; content and source identities remain immutable. */
+export async function rebindBatchRemixReferences(root, sourceDirectory, memberDirectory, selected) {
+    workspaceDirectoryNameSchema.parse(sourceDirectory);
+    workspaceDirectoryNameSchema.parse(memberDirectory);
+    const rootReal = await realpath(root);
+    let items;
+    try {
+        items = await readManifest(rootReal);
+    }
+    catch (error) {
+        if (!selected.length)
+            return;
+        throw error;
+    }
+    for (const reference of selected) {
+        const record = items.find(item => item.referenceId === reference.referenceId);
+        if (reference.directoryName !== sourceDirectory || !record || record.contentHash !== reference.snapshotHash)
+            throw new RemixReferenceError('context_remix_reference_changed');
+    }
+    if (selected.length) {
+        const manifest = JSON.parse((await readFileSafely(rootReal, WORKSPACE_REMIX_REFERENCES_MANIFEST, MANIFEST_MAX_BYTES)).toString('utf8'));
+        if (Array.isArray(manifest.batchPolicyWithheldReferenceIds) && selected.some(reference => manifest.batchPolicyWithheldReferenceIds.includes(reference.referenceId)))
+            throw new RemixReferenceError('batch_reference_files_withheld');
+    }
+    // Selected references must be complete. Other records need only valid metadata to be rebound;
+    // their contents remain subject to the normal checks when the user later lists or selects them.
+    const rebound = [];
+    const writable = [];
+    for (const record of items) {
+        const isSelected = selected.some(reference => reference.referenceId === record.referenceId);
+        try {
+            if (record.directoryName !== sourceDirectory && record.directoryName !== memberDirectory)
+                throw new RemixReferenceError('remix_reference_manifest_invalid');
+            const alternate = record.directoryName === sourceDirectory ? memberDirectory : sourceDirectory;
+            if (isSelected)
+                await verifyReference(rootReal, record, record.directoryName, alternate);
+            else
+                await verifyReferenceMetadata(rootReal, record, record.directoryName, alternate);
+            const next = { ...record, directoryName: memberDirectory };
+            rebound.push(next);
+            writable.push(next);
+        }
+        catch (error) {
+            if (isSelected)
+                throw error;
+            rebound.push(record);
+        }
+    }
+    if (!items.length)
+        return;
+    const metadata = await safeDirectory(rootReal, '.playcraft');
+    const atomicWrite = async (destination, body) => {
+        const temporary = join(metadata, `.batch-reference-${randomUUID()}.tmp`);
+        try {
+            // shared
+            await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    };
+    for (const record of writable) {
+        const target = await safeDirectory(rootReal, record.path);
+        await atomicWrite(join(target, RECEIPT), JSON.stringify(record));
+    }
+    await atomicWrite(join(metadata, 'remix-references.json'), JSON.stringify({ version: 1, items: rebound }));
+}
 /** Reads revalidate the snapshot, so changed/deleted files cannot silently remain attached to a turn. */
 export async function listWorkspaceRemixReferences(root, directoryName = 'basic') {
     workspaceDirectoryNameSchema.parse(directoryName);

package/dist/workspace-runtime/workspaces/remote-attach-marker.js

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+function markerPath(state, workspaceId) {
+    return join(state.config.stateDir, 'workspace-remote-attach', `${workspaceId}.json`);
+}
+/** Caller holds the workspace journal lock. Never replace a different unfinished attach. */
+export async function markRemoteAttachPending(state, workspaceId, repositoryUrl, branchName) {
+    const path = markerPath(state, workspaceId);
+    const directory = join(state.config.stateDir, 'workspace-remote-attach');
+    // private: the attach marker is controller state outside the shared workspace tree.
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const expected = { repositoryUrl, branchName };
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    // private: only the controller reads an unfinished attach back.
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(expected));
+        await handle.sync();
+        await handle.close();
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const previous = JSON.parse(await readFile(path, 'utf8'));
+            if (previous.repositoryUrl !== repositoryUrl || previous.branchName !== branchName)
+                throw new Error('batch_source_identity_mismatch');
+        }
+        const folder = await open(directory, 'r');
+        try {
+            await folder.sync();
+        }
+        finally {
+            await folder.close();
+        }
+    }
+    finally {
+        await handle.close();
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+/** Caller holds the workspace journal lock to serialize with attach and marker removal. */
+export async function remoteAttachPending(state, workspaceId) {
+    try {
+        await readFile(markerPath(state, workspaceId));
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "private": false,
   "type": "module",
   "engines": {
@@ -56,8 +56,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.68",
-    "@playcraft/common": "0.1.68",
+    "@playcraft/build": "0.1.70",
+    "@playcraft/common": "0.1.70",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

package/project-template-v2/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

package/project-template-v2/.playcraft/skills.lock.json

@@ -171,8 +171,8 @@
     },
     {
       "skillRef": "remix/playcraft-workspace-assets",
-      "version": "1.0.0",
-      "artifactHash": "f098949b043a229e561d92a34c3a65b44ffbd83d1758ef30ac09d2d0d5ea2570",
+      "version": "1.1.0",
+      "artifactHash": "bb8d3c17953e85e006f5de75bd267d29ea9cef329298d169ba57e11f59f4f21e",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-workspace-assets"
     }

package/project-templates/phaser/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务
 

package/project-templates/threejs/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: playcraft-workspace-assets
-description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+description: Use when selecting 3D asset kits, finding or downloading shared library assets, or managing durable media generation tasks in a PlayCraft cloud workspace.
 compatibility: agent,opencode
-version: 1.0.0
+version: 1.1.0
 surfaces:
   - sandbox-agent
 ---
@@ -13,6 +13,17 @@ surfaces:
 
 ## 查找并复用素材
 
+一组三维物件的检索入口为素材包；包内覆盖结果给出逐项可用模型及缺口：
+
+```bash
+playcraft library kits --search "家具" --json
+playcraft library kit kenney-furniture-kit --needs "椅子,桌子,打印机" --json
+```
+
+素材包是主题与风格的逻辑集合，区别于一起下载的文件集合及版权来源归档。`coverageScope: partial` 表示仅部分收录；`members` 才是当前可用模型及确切版本，`needCoverage` 返回同包每项需求的候选或缺口。`inventoryRevision` 只标识当前库存，不是持久保存的历史整包版本。`styleGuidance` 提供设计参照，`compatibility` 未验证的单位、朝向和连接规则不能用于兼容性承诺；生成供应商不会自动匹配该风格。
+
+包内模型和独立素材都使用以下单素材入口。模型下载加 `--revision-id <revisionId>`，保留命令生成的 `.playcraft/asset-provenance.json`、许可和来源说明；工程文件路径、模型版本与来源记录共同标识实际使用实例。
+
 ```bash
 playcraft library search "角色" --type texture --tags character --limit 20 --json
 playcraft library facets --json
@@ -21,9 +32,9 @@ playcraft library files <assetId> --json
 playcraft library download <assetId> --output ./assets/character
 ```
 
-检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+检索字段是名称、素材库路径和标签，已审核模型还支持别名、用途、许可及能力筛选；也可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。预览图不能代替模型或其依赖。
 
-`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+`--output` 对单文件表示文件路径，对文件集合表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。文件集合包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
 
 ## 创建持久化生成任务