Update Match3D/image-generation docs & code

Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.

packages/shared/src/contracts/match3dWorks.ts

@@ -73,7 +73,9 @@ export interface PersistMatch3DGeneratedModelResponse {
 
 export interface GenerateMatch3DCoverImageRequest {
   prompt: string;
+  uploadedImageSrc?: string | null;
   referenceImageSrc?: string | null;
+  referenceImageSrcs?: string[];
 }
 
 export interface GenerateMatch3DCoverImageResponse {
@@ -95,8 +97,23 @@ export interface GenerateMatch3DBackgroundImageResponse {
   prompt: string;
 }
 
+export interface GenerateMatch3DContainerImageRequest {
+  prompt: string;
+}
+
+export interface GenerateMatch3DContainerImageResponse {
+  item: Match3DWorkProfile;
+  containerImageSrc: string;
+  containerImageObjectKey: string;
+  generatedBackgroundAsset: Match3DGeneratedBackgroundAsset;
+  prompt: string;
+}
+
+export type GenerateMatch3DItemAssetsMode = 'append' | 'replace';
+
 export interface GenerateMatch3DItemAssetsRequest {
   itemNames: string[];
+  mode?: GenerateMatch3DItemAssetsMode;
 }
 
 export interface GenerateMatch3DItemAssetsResponse {

packages/shared/src/contracts/puzzleRuntimeSession.ts

@@ -58,6 +58,7 @@ export interface PuzzleRuntimeLevelSnapshot {
   themeTags: string[];
   coverImageSrc: string | null;
   uiBackgroundImageSrc?: string | null;
+  uiBackgroundImageObjectKey?: string | null;
   backgroundMusic?: CreationAudioAsset | null;
   board: PuzzleBoardSnapshot;
   status: PuzzleRuntimeLevelStatus;