@drawcall/design 0.5.2 → 0.5.4

package/dist/cli.js

@@ -4,7 +4,7 @@ import { Command, Option } from "commander";
 import { clearConfig, getConfigPath, saveConfig } from "./config.js";
 import { getCliClient } from "./cli-client.js";
 import { readImageInput } from "./image.js";
-import { designSkill } from "./skill.generated.js";
+import { cliDesignSkill } from "./skill.generated.js";
 import { parseFrameSize } from "./target.js";
 import { createClient, DEFAULT_BASE_URL } from "./v1/client.js";
 import { designIdSchema, marketAssetSchema } from "./v1/schemas.js";
@@ -20,7 +20,7 @@ program
     .command("skill")
     .description("Print the Drawcall Design skill")
     .action(() => {
-    process.stdout.write(designSkill);
+    process.stdout.write(cliDesignSkill);
 });
 program
     .command("login")

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export * as v1 from "./v1/index.js";
-export { designSkill } from "./skill.generated.js";
+export { cliDesignSkill, mcpDesignSkill } from "./skill.generated.js";
 export { frameCreationCapabilities, type FrameCreationCapability, type FrameCreationCapabilityId, type FrameCreationInput, } from "./v1/capabilities.js";
 export { cameraPoseSchema, IMAGE_GENERATION_MODEL, IMAGE_GENERATION_PROVIDER, } from "./v1/schemas.js";
 export { parseFrameSize } from "./target.js";
 export { projectFrameLayoutSchema, projectFrameRecordSchema, projectGltsFrameRecordSchema, projectImageFrameRecordSchema, projectMarketFileSchema, projectMarketFrameRecordSchema, projectPresenceClientMessageSchema, projectPresenceServerMessageSchema, projectStateSchema, type ProjectFrameLayout, type ProjectFrameRecord, type ProjectGltsFrameRecord, type ProjectImageFrameRecord, type ProjectMarketFile, type ProjectMarketFrameRecord, type ProjectPresenceClientMessage, type ProjectPresenceServerMessage, type ProjectState, } from "./project-state.js";
-export { acknowledgesInspection, cameraCaptureCommandSchema, cameraCaptureResultSchema, cameraMessageTypes, gltsExportCancelCommandSchema, gltsExportCancelledResultSchema, gltsExportCommandSchema, gltsExportFrameMessageSchema, gltsExportMessageTypes, gltsExportParentMessageSchema, gltsExportResultSchema, gltsRuntimeExportFormatSchema, inspectionCommandSchema, inspectionFrameMessageSchema, inspectionMessageTypes, projectSyncUrl, sourceFileChangeSchema, sourceFileMessageTypes, sourceFileReloadResultSchema, sourceFilesChangedMessageSchema, type GltsExportCancelCommand, type GltsExportCancelledResult, type GltsExportCommand, type GltsExportFrameMessage, type GltsExportParentMessage, type GltsExportResult, type GltsRuntimeExportFormat, type CameraCaptureCommand, type CameraCaptureFailure, type CameraCaptureResult, type InspectionAppliedMessage, type InspectionCommand, type InspectionFrameMessage, type SourceFileChange, type SourceFileReloadResult, type SourceFilesChangedMessage, } from "./protocol.js";
+export { acknowledgesInspection, cameraCaptureCommandSchema, cameraCaptureResultSchema, cameraMessageTypes, gltsExportCancelCommandSchema, gltsExportCancelledResultSchema, gltsExportCommandSchema, gltsExportFrameMessageSchema, gltsExportMessageTypes, gltsExportParentMessageSchema, gltsExportResultSchema, gltsRuntimeExportFormatSchema, immersiveCommandSchema, immersiveFrameMessageSchema, immersiveMessageTypes, immersiveModeSchema, inspectionCommandSchema, inspectionFrameMessageSchema, inspectionMessageTypes, projectSyncUrl, sourceFileChangeSchema, sourceFileMessageTypes, sourceFileReloadResultSchema, sourceFilesChangedMessageSchema, type GltsExportCancelCommand, type GltsExportCancelledResult, type GltsExportCommand, type GltsExportFrameMessage, type GltsExportParentMessage, type GltsExportResult, type GltsRuntimeExportFormat, type CameraCaptureCommand, type CameraCaptureFailure, type CameraCaptureResult, type InspectionAppliedMessage, type InspectionCommand, type InspectionFrameMessage, type ImmersiveCommand, type ImmersiveFrameMessage, type ImmersiveMode, type SourceFileChange, type SourceFileReloadResult, type SourceFilesChangedMessage, } from "./protocol.js";
 export type { BinaryFile, CameraPose, CreateFrame, CreateProjectFromBrief, CreateGltsFrame, CreateImageFrame, CreateMarketFrame, GenerateImageFrame, DesignFile, FileList, FileMutation, FrameExport, Frame, GltsFrame, GltsFrameExport, ImageFrame, ImageFrameExport, ImageGenerationOperation, ImageGenerationProvenance, ImageGenerationResult, MarketFrame, MarketFrameExport, Project, ProjectDerivationStatus, Screenshot, TextFile, User, } from "./v1/schemas.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export * as v1 from "./v1/index.js";
-export { designSkill } from "./skill.generated.js";
+export { cliDesignSkill, mcpDesignSkill } from "./skill.generated.js";
 export { frameCreationCapabilities, } from "./v1/capabilities.js";
 export { cameraPoseSchema, IMAGE_GENERATION_MODEL, IMAGE_GENERATION_PROVIDER, } from "./v1/schemas.js";
 export { parseFrameSize } from "./target.js";
 export { projectFrameLayoutSchema, projectFrameRecordSchema, projectGltsFrameRecordSchema, projectImageFrameRecordSchema, projectMarketFileSchema, projectMarketFrameRecordSchema, projectPresenceClientMessageSchema, projectPresenceServerMessageSchema, projectStateSchema, } from "./project-state.js";
-export { acknowledgesInspection, cameraCaptureCommandSchema, cameraCaptureResultSchema, cameraMessageTypes, gltsExportCancelCommandSchema, gltsExportCancelledResultSchema, gltsExportCommandSchema, gltsExportFrameMessageSchema, gltsExportMessageTypes, gltsExportParentMessageSchema, gltsExportResultSchema, gltsRuntimeExportFormatSchema, inspectionCommandSchema, inspectionFrameMessageSchema, inspectionMessageTypes, projectSyncUrl, sourceFileChangeSchema, sourceFileMessageTypes, sourceFileReloadResultSchema, sourceFilesChangedMessageSchema, } from "./protocol.js";
+export { acknowledgesInspection, cameraCaptureCommandSchema, cameraCaptureResultSchema, cameraMessageTypes, gltsExportCancelCommandSchema, gltsExportCancelledResultSchema, gltsExportCommandSchema, gltsExportFrameMessageSchema, gltsExportMessageTypes, gltsExportParentMessageSchema, gltsExportResultSchema, gltsRuntimeExportFormatSchema, immersiveCommandSchema, immersiveFrameMessageSchema, immersiveMessageTypes, immersiveModeSchema, inspectionCommandSchema, inspectionFrameMessageSchema, inspectionMessageTypes, projectSyncUrl, sourceFileChangeSchema, sourceFileMessageTypes, sourceFileReloadResultSchema, sourceFilesChangedMessageSchema, } from "./protocol.js";

package/dist/protocol.d.ts

@@ -7,6 +7,28 @@ export declare const inspectionMessageTypes: {
     readonly ready: "drawcall:inspection:ready";
     readonly set: "drawcall:inspection:set";
 };
+export declare const immersiveMessageTypes: {
+    readonly enter: "drawcall:immersive:enter";
+    readonly error: "drawcall:immersive:error";
+    readonly exit: "drawcall:immersive:exit";
+};
+export declare const immersiveModeSchema: z.ZodEnum<{
+    ar: "ar";
+    vr: "vr";
+}>;
+export declare const immersiveCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"drawcall:immersive:enter">;
+    mode: z.ZodEnum<{
+        ar: "ar";
+        vr: "vr";
+    }>;
+}, z.core.$strict>;
+export declare const immersiveFrameMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"drawcall:immersive:exit">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"drawcall:immersive:error">;
+    message: z.ZodString;
+}, z.core.$strict>], "type">;
 export declare const gltsExportMessageTypes: {
     readonly cancel: "drawcall:export:cancel";
     readonly cancelled: "drawcall:export:cancelled";
@@ -171,6 +193,9 @@ export declare const inspectionFrameMessageSchema: z.ZodDiscriminatedUnion<[z.Zo
     type: z.ZodLiteral<"drawcall:inspection:exit">;
 }, z.core.$strict>], "type">;
 export type InspectionCommand = z.infer<typeof inspectionCommandSchema>;
+export type ImmersiveMode = z.infer<typeof immersiveModeSchema>;
+export type ImmersiveCommand = z.infer<typeof immersiveCommandSchema>;
+export type ImmersiveFrameMessage = z.infer<typeof immersiveFrameMessageSchema>;
 export type CameraCaptureCommand = z.infer<typeof cameraCaptureCommandSchema>;
 export type CameraCaptureResult = z.infer<typeof cameraCaptureResultSchema>;
 export type SourceFileChange = z.infer<typeof sourceFileChangeSchema>;

package/dist/protocol.js

@@ -8,6 +8,27 @@ export const inspectionMessageTypes = {
     ready: "drawcall:inspection:ready",
     set: "drawcall:inspection:set",
 };
+export const immersiveMessageTypes = {
+    enter: "drawcall:immersive:enter",
+    error: "drawcall:immersive:error",
+    exit: "drawcall:immersive:exit",
+};
+export const immersiveModeSchema = z.enum(["ar", "vr"]);
+export const immersiveCommandSchema = z
+    .object({
+    type: z.literal(immersiveMessageTypes.enter),
+    mode: immersiveModeSchema,
+})
+    .strict();
+export const immersiveFrameMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal(immersiveMessageTypes.exit) }).strict(),
+    z
+        .object({
+        type: z.literal(immersiveMessageTypes.error),
+        message: z.string().min(1),
+    })
+        .strict(),
+]);
 export const gltsExportMessageTypes = {
     cancel: "drawcall:export:cancel",
     cancelled: "drawcall:export:cancelled",

package/dist/skill.generated.d.ts

@@ -1 +1,2 @@
-export declare const designSkill = "---\nname: drawcall-design\ndescription: Create, modify, inspect, and screenshot 3D assets and reference frames in Drawcall Design. Use for Drawcall Design projects, frames, the project filesystem, GLTS assets, or Drawcall Market frames. Do not use for full games or applications.\n---\n\n# Drawcall Design\n\nUse the Drawcall Design MCP tools when available. Otherwise use `npx @drawcall/design`. Design is a remote, current-state canvas: inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level folder, `/<frame-id>/`. The CLI selects the project with `-p <project-id>`; its file paths are exactly the absolute paths inside that project, for example `/f7k3m9q2x8vd/index.glts`.\n\nCreate frames with an explicit type. GLTS frames require `--size`; image and Market frames derive their canvas size. A Market frame requires an exact public asset reference, `name@version`.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from \"three\";\nimport Wheel from \"./parts/wheel.glts\";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. Use a project-absolute path to import a GLTS asset from another frame:\n\n```ts\nimport Chassis from \"/other-frame-id/index.glts\";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL(\"/market-frame-id/models/car.glb\", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nAfter every meaningful visual change, take and inspect a screenshot. Iterate until the asset, camera, composition, and requested frame size are right.\n";
+export declare const mcpDesignSkill = "---\nname: drawcall-design\ndescription: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.\n---\n\n# Drawcall Design\n\n## MCP transport\n\nMCP tools are the only Drawcall transport in this environment. Do not invoke a CLI or shell, make direct HTTP requests, or search the web for another transport. A failed MCP call does not make MCP unavailable.\n\nUse `generate_image` only when the user asks for a 2D image or reference. A 3D object, scene, or reusable asset is GLTS work, even when the user calls its canvas container a frame.\n\nTool arguments are JSON objects. File tools identify their target with `project` and a project-absolute `path`; they do not accept a separate `frame` argument. Call `list_files` and pass one of its returned paths unchanged.\n\n```json\n[\n  {\n    \"tool\": \"list_projects\",\n    \"arguments\": {}\n  },\n  {\n    \"tool\": \"list_frames\",\n    \"arguments\": {\n      \"project\": \"r6z2n9k4x8m1qc\"\n    }\n  },\n  {\n    \"tool\": \"list_files\",\n    \"arguments\": {\n      \"project\": \"r6z2n9k4x8m1qc\"\n    }\n  },\n  {\n    \"tool\": \"read_file\",\n    \"arguments\": {\n      \"project\": \"r6z2n9k4x8m1qc\",\n      \"path\": \"/a4z8m2q7v9kcde/index.glts\"\n    }\n  },\n  {\n    \"tool\": \"edit_file\",\n    \"arguments\": {\n      \"project\": \"r6z2n9k4x8m1qc\",\n      \"path\": \"/a4z8m2q7v9kcde/index.glts\",\n      \"oldText\": \"color: 0xffffff\",\n      \"newText\": \"color: 0x000000\"\n    }\n  }\n]\n```\n\nDesign is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.\n\nCreate frames with an explicit type. Choose the type from the requested artifact, not from the word \"frame\": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## Failures\n\nAn error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from \"three\";\nimport Wheel from \"./parts/wheel.glts\";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. When a reusable 3D asset belongs in another frame, keep it in its own GLTS frame and import its root by project-absolute path from the consuming frame. Instantiate that import as often as needed instead of copying its source:\n\n```ts\nimport Chassis from \"/other-frame-id/index.glts\";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL(\"/market-frame-id/models/car.glb\", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nTreat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.\n";
+export declare const cliDesignSkill = "---\nname: drawcall-design\ndescription: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.\n---\n\n# Drawcall Design\n\n## CLI transport\n\nThe CLI is the only Drawcall transport in this environment. Do not search for MCP tools or make direct HTTP requests. A failed CLI command does not justify switching transport.\n\nCLI calls are shell command strings. Select the project with `-p <project-id>`. File commands take project-absolute paths that include the frame ID.\n\n```sh\nnpx @drawcall/design project list\nnpx @drawcall/design -p r6z2n9k4x8m1qc frame list\nnpx @drawcall/design -p r6z2n9k4x8m1qc ls\nnpx @drawcall/design -p r6z2n9k4x8m1qc read /a4z8m2q7v9kcde/index.glts\nnpx @drawcall/design -p r6z2n9k4x8m1qc edit /a4z8m2q7v9kcde/index.glts 'color: 0xffffff' 'color: 0x000000'\n```\n\nDesign is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.\n\nCreate frames with an explicit type. Choose the type from the requested artifact, not from the word \"frame\": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## Failures\n\nAn error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from \"three\";\nimport Wheel from \"./parts/wheel.glts\";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. When a reusable 3D asset belongs in another frame, keep it in its own GLTS frame and import its root by project-absolute path from the consuming frame. Instantiate that import as often as needed instead of copying its source:\n\n```ts\nimport Chassis from \"/other-frame-id/index.glts\";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL(\"/market-frame-id/models/car.glb\", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nTreat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.\n";

package/dist/skill.generated.js

@@ -1,2 +1,3 @@
-// Generated from skills/drawcall-design/SKILL.md.
-export const designSkill = '---\nname: drawcall-design\ndescription: Create, modify, inspect, and screenshot 3D assets and reference frames in Drawcall Design. Use for Drawcall Design projects, frames, the project filesystem, GLTS assets, or Drawcall Market frames. Do not use for full games or applications.\n---\n\n# Drawcall Design\n\nUse the Drawcall Design MCP tools when available. Otherwise use `npx @drawcall/design`. Design is a remote, current-state canvas: inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level folder, `/<frame-id>/`. The CLI selects the project with `-p <project-id>`; its file paths are exactly the absolute paths inside that project, for example `/f7k3m9q2x8vd/index.glts`.\n\nCreate frames with an explicit type. GLTS frames require `--size`; image and Market frames derive their canvas size. A Market frame requires an exact public asset reference, `name@version`.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from "three";\nimport Wheel from "./parts/wheel.glts";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. Use a project-absolute path to import a GLTS asset from another frame:\n\n```ts\nimport Chassis from "/other-frame-id/index.glts";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL("/market-frame-id/models/car.glb", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nAfter every meaningful visual change, take and inspect a screenshot. Iterate until the asset, camera, composition, and requested frame size are right.\n';
+// Generated from skill/SKILL.template.md.
+export const mcpDesignSkill = '---\nname: drawcall-design\ndescription: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.\n---\n\n# Drawcall Design\n\n## MCP transport\n\nMCP tools are the only Drawcall transport in this environment. Do not invoke a CLI or shell, make direct HTTP requests, or search the web for another transport. A failed MCP call does not make MCP unavailable.\n\nUse `generate_image` only when the user asks for a 2D image or reference. A 3D object, scene, or reusable asset is GLTS work, even when the user calls its canvas container a frame.\n\nTool arguments are JSON objects. File tools identify their target with `project` and a project-absolute `path`; they do not accept a separate `frame` argument. Call `list_files` and pass one of its returned paths unchanged.\n\n```json\n[\n  {\n    "tool": "list_projects",\n    "arguments": {}\n  },\n  {\n    "tool": "list_frames",\n    "arguments": {\n      "project": "r6z2n9k4x8m1qc"\n    }\n  },\n  {\n    "tool": "list_files",\n    "arguments": {\n      "project": "r6z2n9k4x8m1qc"\n    }\n  },\n  {\n    "tool": "read_file",\n    "arguments": {\n      "project": "r6z2n9k4x8m1qc",\n      "path": "/a4z8m2q7v9kcde/index.glts"\n    }\n  },\n  {\n    "tool": "edit_file",\n    "arguments": {\n      "project": "r6z2n9k4x8m1qc",\n      "path": "/a4z8m2q7v9kcde/index.glts",\n      "oldText": "color: 0xffffff",\n      "newText": "color: 0x000000"\n    }\n  }\n]\n```\n\nDesign is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.\n\nCreate frames with an explicit type. Choose the type from the requested artifact, not from the word "frame": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## Failures\n\nAn error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from "three";\nimport Wheel from "./parts/wheel.glts";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. When a reusable 3D asset belongs in another frame, keep it in its own GLTS frame and import its root by project-absolute path from the consuming frame. Instantiate that import as often as needed instead of copying its source:\n\n```ts\nimport Chassis from "/other-frame-id/index.glts";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL("/market-frame-id/models/car.glb", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nTreat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.\n';
+export const cliDesignSkill = '---\nname: drawcall-design\ndescription: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.\n---\n\n# Drawcall Design\n\n## CLI transport\n\nThe CLI is the only Drawcall transport in this environment. Do not search for MCP tools or make direct HTTP requests. A failed CLI command does not justify switching transport.\n\nCLI calls are shell command strings. Select the project with `-p <project-id>`. File commands take project-absolute paths that include the frame ID.\n\n```sh\nnpx @drawcall/design project list\nnpx @drawcall/design -p r6z2n9k4x8m1qc frame list\nnpx @drawcall/design -p r6z2n9k4x8m1qc ls\nnpx @drawcall/design -p r6z2n9k4x8m1qc read /a4z8m2q7v9kcde/index.glts\nnpx @drawcall/design -p r6z2n9k4x8m1qc edit /a4z8m2q7v9kcde/index.glts \'color: 0xffffff\' \'color: 0x000000\'\n```\n\nDesign is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.\n\n## Project filesystem\n\nA project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.\n\nCreate frames with an explicit type. Choose the type from the requested artifact, not from the word "frame": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.\n\nRead a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.\n\n## Failures\n\nAn error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.\n\n## GLTS assets\n\nA GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.\n\nAuthor GLTS scenes top-down: create the root entry scene first, reference the child `.glts` assets it will compose, then implement those children progressively. A missing `.glts` import renders as a glowing marker labeled with its filename until the real file is written, so the completed parts of the scene remain visible. Treat the marker and its console warning as a temporary missing-dependency diagnostic, not as authored content.\n\n```ts\nimport * as THREE from "three";\nimport Wheel from "./parts/wheel.glts";\n\nexport default class Racecar extends THREE.Group {\n  constructor() {\n    super();\n    this.add(new Wheel());\n  }\n}\n```\n\nUse relative `.glts` imports within a frame. When a reusable 3D asset belongs in another frame, keep it in its own GLTS frame and import its root by project-absolute path from the consuming frame. Instantiate that import as often as needed instead of copying its source:\n\n```ts\nimport Chassis from "/other-frame-id/index.glts";\n```\n\nFor a non-GLTS file from an image or Market frame, preserve the project filesystem URL through `import.meta.url`:\n\n```ts\nconst modelUrl = new URL("/market-frame-id/models/car.glb", import.meta.url);\n```\n\nGLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.\n\nThe viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.\n\nTreat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.\n';

package/dist/v1/contract.js

@@ -1,10 +1,12 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
 import { projectFrameLayoutSchema } from "../project-state.js";
-import { cameraPoseSchema, createFrameSchema, createProjectFromBriefSchema, designIdSchema, fileListSchema, fileMutationSchema, fileSchema, fileTextSchema, frameExportSchema, frameNameSchema, frameSchema, generateImageFrameSchema, projectDirectoryPathSchema, projectNameSchema, projectPathSchema, projectSchema, screenshotSchema, userSchema, } from "./schemas.js";
+import { cameraPoseSchema, createFrameSchema, createProjectFromBriefSchema, designIdSchema, fileListSchema, fileMutationSchema, fileSchema, fileTextSchema, frameExportSchema, frameNameSchema, frameSchema, generateImageFrameSchema, projectDirectoryPathSchema, projectFilePathSchema, projectNameSchema, projectSchema, screenshotSchema, userSchema, } from "./schemas.js";
 const projectInputSchema = z.object({ project: designIdSchema });
 const frameInputSchema = projectInputSchema.extend({ frame: designIdSchema });
-const fileInputSchema = projectInputSchema.extend({ path: projectPathSchema });
+const fileInputSchema = projectInputSchema.extend({
+    path: projectFilePathSchema,
+});
 const deletedSchema = z.object({ id: designIdSchema });
 export const contract = {
     user: {

package/dist/v1/schemas.d.ts

@@ -35,6 +35,7 @@ export declare const imageUrlSchema: z.ZodString;
 export declare const projectPathSchema: z.ZodString;
 /** A project directory path. `/` denotes the project root. */
 export declare const projectDirectoryPathSchema: z.ZodUnion<readonly [z.ZodLiteral<"/">, z.ZodString]>;
+export declare const projectFilePathSchema: z.ZodString;
 export declare const fileTextSchema: z.ZodString;
 export declare const marketAssetNameSchema: z.ZodString;
 export declare const marketAssetVersionSchema: z.ZodString;

package/dist/v1/schemas.js

@@ -5,7 +5,7 @@ export const MAX_IMAGE_GENERATION_PROMPT_LENGTH = 2_048;
 export const MAX_IMAGE_GENERATION_REFERENCES = 4;
 export const designIdSchema = z
     .string()
-    .regex(/^[a-z0-9]{14}$/, "IDs are 14 lowercase alphanumeric characters");
+    .regex(/^[a-z0-9]{14}$/, "IDs are exactly 14 lowercase alphanumeric characters; use an ID returned by a list operation");
 export const projectNameSchema = z
     .string()
     .trim()
@@ -66,8 +66,11 @@ export const projectPathSchema = z.string().max(1_024).refine(isProjectPath, {
 export const projectDirectoryPathSchema = z
     .union([z.literal("/"), projectPathSchema])
     .refine((path) => path === "/" || !path.endsWith("/"), {
-    message: "Directory paths cannot end with /",
+    message: "Directory paths cannot end with /. Use /<frame-id> or omit the path to list the entire project",
 });
+export const projectFilePathSchema = projectPathSchema
+    .regex(/^\/[a-z0-9]{14}\/.+/, "Project file paths must include a frame ID and filename, for example /a4z8m2q7v9kcde/index.glts")
+    .describe("Project-absolute file path including the frame ID, for example /a4z8m2q7v9kcde/index.glts");
 export const fileTextSchema = z.string().max(MAX_FILE_LENGTH);
 export const marketAssetNameSchema = z
     .string()
@@ -148,7 +151,7 @@ export const imageGenerationProvenanceSchema = z.discriminatedUnion("provider",
 ]);
 export const imageFrameSchema = frameBaseSchema.extend({
     type: z.literal("image"),
-    file: projectPathSchema,
+    file: projectFilePathSchema,
     provenance: imageGenerationProvenanceSchema.optional(),
 });
 export const marketFrameSchema = frameBaseSchema.extend({
@@ -273,17 +276,17 @@ export const generateImageFrameSchema = z
     }
 });
 export const fileListSchema = z.object({
-    paths: z.array(projectPathSchema),
+    paths: z.array(projectFilePathSchema),
 });
 export const textFileSchema = z.object({
     type: z.literal("text"),
-    path: projectPathSchema,
+    path: projectFilePathSchema,
     text: z.string(),
     mediaType: z.literal("text/plain"),
 });
 export const binaryFileSchema = z.object({
     type: z.literal("binary"),
-    path: projectPathSchema,
+    path: projectFilePathSchema,
     url: httpUrlSchema,
     mediaType: z.string().min(1),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawcall/design",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Typed API and remote CLI for Drawcall Design",
   "repository": {
     "type": "git",

package/skills/drawcall-design/SKILL.md

@@ -1,20 +1,38 @@
 ---
 name: drawcall-design
-description: Create, modify, inspect, and screenshot 3D assets and reference frames in Drawcall Design. Use for Drawcall Design projects, frames, the project filesystem, GLTS assets, or Drawcall Market frames. Do not use for full games or applications.
+description: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.
 ---
 
 # Drawcall Design
 
-Use the Drawcall Design MCP tools when available. Otherwise use `npx @drawcall/design`. Design is a remote, current-state canvas: inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.
+## CLI transport
+
+The CLI is the only Drawcall transport in this environment. Do not search for MCP tools or make direct HTTP requests. A failed CLI command does not justify switching transport.
+
+CLI calls are shell command strings. Select the project with `-p <project-id>`. File commands take project-absolute paths that include the frame ID.
+
+```sh
+npx @drawcall/design project list
+npx @drawcall/design -p r6z2n9k4x8m1qc frame list
+npx @drawcall/design -p r6z2n9k4x8m1qc ls
+npx @drawcall/design -p r6z2n9k4x8m1qc read /a4z8m2q7v9kcde/index.glts
+npx @drawcall/design -p r6z2n9k4x8m1qc edit /a4z8m2q7v9kcde/index.glts 'color: 0xffffff' 'color: 0x000000'
+```
+
+Design is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.
 
 ## Project filesystem
 
-A project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level folder, `/<frame-id>/`. The CLI selects the project with `-p <project-id>`; its file paths are exactly the absolute paths inside that project, for example `/f7k3m9q2x8vd/index.glts`.
+A project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.
 
-Create frames with an explicit type. GLTS frames require `--size`; image and Market frames derive their canvas size. A Market frame requires an exact public asset reference, `name@version`.
+Create frames with an explicit type. Choose the type from the requested artifact, not from the word "frame": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.
 
 Read a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.
 
+## Failures
+
+An error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.
+
 ## GLTS assets
 
 A GLTS frame contains only `.glts` files. `index.glts` is its optional root asset; without it the frame renders empty. Every `.glts` file is a trusted TypeScript ESM module that default-exports a no-argument class derived from `THREE.Object3D`. Avoid top-level side effects because reload evaluates the module again. Implement `dispose()` when the asset exclusively owns disposable resources.
@@ -33,7 +51,7 @@ export default class Racecar extends THREE.Group {
 }
 ```
 
-Use relative `.glts` imports within a frame. Use a project-absolute path to import a GLTS asset from another frame:
+Use relative `.glts` imports within a frame. When a reusable 3D asset belongs in another frame, keep it in its own GLTS frame and import its root by project-absolute path from the consuming frame. Instantiate that import as often as needed instead of copying its source:
 
 ```ts
 import Chassis from "/other-frame-id/index.glts";
@@ -49,4 +67,4 @@ GLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It do
 
 The viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.
 
-After every meaningful visual change, take and inspect a screenshot. Iterate until the asset, camera, composition, and requested frame size are right.
+Treat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.