docs: add comprehensive metadata.json schema documentation (#856)

- Create docs/metadata-json-schema.md with complete field reference
  - All base fields for LoRA, Checkpoint, and Embedding models
  - Complete civitai object structure with Used vs Stored field classification
  - Model-level fields (allowCommercialUse, allowDerivatives, etc.)
  - Creator fields (username, image)
  - customImages structure with actual field names and types
  - Field behavior categories (Auto-Updated, Set Once, User-Editable)

- Add .specs/metadata.schema.json for programmatic validation
  - JSON Schema draft-07 format
  - oneOf schemas for each model type
  - Definitions for civitaiObject and usageTips

- Add example metadata files for each model type
  - lora-civitai.json: LoRA with full Civitai data
  - lora-custom.json: User-defined LoRA with trigger words
  - lora-no-triggerwords.json: LoRA without trigger words
  - checkpoint-civitai.json: Checkpoint from Civitai
  - embedding-custom.json: Custom embedding

Key clarifications:
  - modified: Import timestamp (Set Once, never changes after import)
  - size: File size at import time (Set Once)
  - base_model: Optional with actual values (SDXL 1.0, Flux.1 D, etc.)
  - model_type: Used in metadata.json (not sub_type which is internal)
  - allowCommercialUse: ["Image", "Video", "RentCivit", "Rent"]
  - civitai.files/images: Marked as Used by Lora Manager
  - User-editable fields clearly documented (model_name, tags, etc.)

examples/metadata/checkpoint-civitai.json

@@ -0,0 +1,41 @@
+{
+  "file_name": "realistic_vision_v5",
+  "model_name": "Realistic Vision v5.0",
+  "file_path": "/home/user/ComfyUI/models/checkpoints/realistic_vision_v5.safetensors",
+  "size": 6943152000,
+  "modified": 1710000000.0,
+  "sha256": "ghi456jkl789012345678901234567890123456789012345678901234567ijkl",
+  "base_model": "SDXL",
+  "preview_url": "/home/user/ComfyUI/models/checkpoints/realistic_vision_v5.preview.png",
+  "preview_nsfw_level": 0,
+  "from_civitai": true,
+  "civitai": {
+    "id": 54321,
+    "modelId": 98765,
+    "name": "v5.0",
+    "description": "Realistic Vision v5.0 - photorealistic checkpoint",
+    "baseModel": "SDXL",
+    "type": "checkpoint",
+    "trainedWords": ["realistic photo", "photorealistic"],
+    "model": {
+      "name": "Realistic Vision",
+      "description": "A photorealistic checkpoint model for SDXL",
+      "tags": ["realistic", "photorealistic", "portrait", "landscape"]
+    },
+    "creator": {
+      "id": 44444,
+      "name": "CheckpointCreator"
+    }
+  },
+  "tags": ["realistic", "photorealistic", "portrait", "landscape"],
+  "modelDescription": "Photorealistic checkpoint model optimized for portraits and landscapes. Works best with positive prompts.",
+  "civitai_deleted": false,
+  "favorite": true,
+  "exclude": false,
+  "db_checked": true,
+  "skip_metadata_refresh": false,
+  "metadata_source": "civitai_api",
+  "last_checked_at": 1710100000.0,
+  "hash_status": "completed",
+  "sub_type": "checkpoint"
+}

examples/metadata/embedding-custom.json

@@ -0,0 +1,24 @@
+{
+  "file_name": "bad_hand_fix",
+  "model_name": "Bad Hand Fix Embedding",
+  "file_path": "/home/user/ComfyUI/models/embeddings/bad_hand_fix.pt",
+  "size": 512000,
+  "modified": 1710000000.0,
+  "sha256": "mno789pqr012345678901234567890123456789012345678901234567890mnop",
+  "base_model": "SDXL",
+  "preview_url": "",
+  "preview_nsfw_level": 0,
+  "from_civitai": false,
+  "civitai": {},
+  "tags": ["fix", "hands", "negative"],
+  "modelDescription": "Textual inversion embedding to fix bad hands in generated images. Use in negative prompts.",
+  "civitai_deleted": false,
+  "favorite": false,
+  "exclude": false,
+  "db_checked": false,
+  "skip_metadata_refresh": false,
+  "metadata_source": null,
+  "last_checked_at": 1710100000.0,
+  "hash_status": "completed",
+  "sub_type": "embedding"
+}

examples/metadata/lora-civitai.json

@@ -0,0 +1,57 @@
+{
+  "file_name": "anime_style_lora",
+  "model_name": "Anime Style LoRA",
+  "file_path": "/home/user/ComfyUI/models/loras/anime_style_lora.safetensors",
+  "size": 104857600,
+  "modified": 1710000000.0,
+  "sha256": "abc123def456789012345678901234567890123456789012345678901234abcd",
+  "base_model": "SDXL",
+  "preview_url": "/home/user/ComfyUI/models/loras/anime_style_lora.preview.png",
+  "preview_nsfw_level": 0,
+  "notes": "",
+  "from_civitai": true,
+  "civitai": {
+    "id": 12345,
+    "modelId": 67890,
+    "name": "v1.0",
+    "description": "Version 1.0 release",
+    "baseModel": "SDXL",
+    "trainedWords": ["anime style", "cel shading"],
+    "model": {
+      "name": "Anime Style LoRA",
+      "description": "A LoRA for creating anime-style images with cel shading effects",
+      "tags": ["anime", "style", "cel shading", "illustration"]
+    },
+    "files": [
+      {
+        "id": 11111,
+        "name": "anime_style_lora.safetensors",
+        "sizeKB": 102400,
+        "primary": true
+      }
+    ],
+    "images": [
+      {
+        "id": 22222,
+        "url": "https://example.com/preview.png",
+        "nsfwLevel": 0
+      }
+    ],
+    "creator": {
+      "id": 33333,
+      "name": "ModelCreator",
+      "image": "https://example.com/avatar.png"
+    }
+  },
+  "tags": ["anime", "style", "cel shading", "illustration"],
+  "modelDescription": "A LoRA for creating anime-style images with cel shading effects. Works best with SDXL models and anime checkpoints.",
+  "civitai_deleted": false,
+  "favorite": true,
+  "exclude": false,
+  "db_checked": true,
+  "skip_metadata_refresh": false,
+  "metadata_source": "civitai_api",
+  "last_checked_at": 1710100000.0,
+  "hash_status": "completed",
+  "usage_tips": "{\"strength_min\":0.3,\"strength_max\":0.8,\"strength\":0.6,\"clip_strength\":0.5}"
+}

examples/metadata/lora-custom.json

@@ -0,0 +1,34 @@
+{
+  "file_name": "custom_effect_lora",
+  "model_name": "My Custom Effect LoRA",
+  "file_path": "/home/user/ComfyUI/models/loras/custom_effect_lora.safetensors",
+  "size": 52428800,
+  "modified": 1710000000.0,
+  "sha256": "def789abc123456789012345678901234567890123456789012345678901efgh",
+  "base_model": "SD1.5",
+  "preview_url": "/home/user/ComfyUI/models/loras/custom_effect_lora.preview.png",
+  "preview_nsfw_level": 0,
+  "notes": "Custom trained LoRA for special effects",
+  "from_civitai": true,
+  "civitai": {
+    "trainedWords": ["custom_effect", "special_fx"],
+    "customImages": [
+      {
+        "url": "custom_example_1.png",
+        "seed": 12345,
+        "prompt": "example prompt 1"
+      }
+    ]
+  },
+  "tags": ["custom", "experimental", "effects"],
+  "modelDescription": "My custom trained LoRA for creating special visual effects",
+  "civitai_deleted": false,
+  "favorite": false,
+  "exclude": false,
+  "db_checked": false,
+  "skip_metadata_refresh": false,
+  "metadata_source": null,
+  "last_checked_at": 1710100000.0,
+  "hash_status": "completed",
+  "usage_tips": "{\"strength\":0.7}"
+}

examples/metadata/lora-no-triggerwords.json

@@ -0,0 +1,25 @@
+{
+  "file_name": "no_trigger_lora",
+  "model_name": "LoRA Without Trigger Words",
+  "file_path": "/home/user/ComfyUI/models/loras/no_trigger_lora.safetensors",
+  "size": 10485760,
+  "modified": 1710000000.0,
+  "sha256": "abc123def456789012345678901234567890123456789012345678901234wxyz",
+  "base_model": "SDXL",
+  "preview_url": "",
+  "preview_nsfw_level": 0,
+  "notes": "",
+  "from_civitai": true,
+  "civitai": {},
+  "tags": ["abstract"],
+  "modelDescription": "A LoRA with no trigger words",
+  "civitai_deleted": false,
+  "favorite": false,
+  "exclude": false,
+  "db_checked": false,
+  "skip_metadata_refresh": false,
+  "metadata_source": null,
+  "last_checked_at": 1710100000.0,
+  "hash_status": "completed",
+  "usage_tips": "{}"
+}