1# Asset Organization Guide
2 
3Guidelines for organizing marketing assets in a structured, searchable system.
4 
5## Directory Structure
6 
7```
8project-root/
9├── .assets/                          # Git-tracked metadata
10│   ├── manifest.json                 # Central asset registry
11│   ├── tags.json                     # Tagging system
12│   ├── versions/                     # Version history
13│   │   └── {asset-id}/
14│   │       └── v{n}.json
15│   └── metadata/                     # Type-specific metadata
16│       ├── designs.json
17│       ├── banners.json
18│       ├── logos.json
19│       └── videos.json
20├── assets/                           # Raw files
21│   ├── designs/
22│   │   ├── campaigns/                # Campaign-specific designs
23│   │   ├── web/                      # Website graphics
24│   │   └── print/                    # Print materials
25│   ├── banners/
26│   │   ├── social-media/             # Platform banners
27│   │   ├── email-headers/            # Email template headers
28│   │   └── landing-pages/            # Hero/section images
29│   ├── logos/
30│   │   ├── full-horizontal/          # Full logo with wordmark
31│   │   ├── icon-only/                # Symbol only
32│   │   ├── monochrome/               # Single color versions
33│   │   └── variations/               # Special versions
34│   ├── videos/
35│   │   ├── ads/                      # Promotional videos
36│   │   ├── tutorials/                # How-to content
37│   │   └── testimonials/             # Customer videos
38│   ├── infographics/                 # Data visualizations
39│   └── generated/                    # AI-generated assets
40│       └── {YYYYMMDD}/               # Date-organized
41```
42 
43## Naming Convention
44 
45### Format
46```
47{type}_{campaign}_{description}_{timestamp}_{variant}.{ext}
48```
49 
50### Components
51| Component | Format | Required | Examples |
52|-----------|--------|----------|----------|
53| type | lowercase | Yes | banner, logo, design, video |
54| campaign | kebab-case | Yes* | claude-launch, q1-promo, evergreen |
55| description | kebab-case | Yes | hero-image, email-header |
56| timestamp | YYYYMMDD | Yes | 20251209 |
57| variant | kebab-case | No | dark-mode, 1x1, mobile |
58 
59*Use "evergreen" for non-campaign assets
60 
61### Examples
62```
63banner_claude-launch_hero-image_20251209_16-9.png
64logo_brand-refresh_horizontal-full-color_20251209.svg
65design_holiday-campaign_email-hero_20251209_dark-mode.psd
66video_product-demo_feature-walkthrough_20251209.mp4
67infographic_evergreen_pricing-comparison_20251209.png
68```
69 
70## Metadata Schema
71 
72### Asset Entry (manifest.json)
73```json
74{
75  "id": "uuid-v4",
76  "name": "Campaign Hero Banner",
77  "type": "banner",
78  "path": "assets/banners/landing-pages/banner_claude-launch_hero-image_20251209.png",
79  "dimensions": { "width": 1920, "height": 1080 },
80  "fileSize": 245760,
81  "mimeType": "image/png",
82  "tags": ["campaign", "hero", "launch"],
83  "status": "approved",
84  "source": {
85    "model": "imagen-4",
86    "prompt": "...",
87    "createdAt": "2025-12-09T10:30:00Z"
88  },
89  "version": 2,
90  "createdBy": "agent:content-creator",
91  "approvedBy": "user:john",
92  "approvedAt": "2025-12-09T14:00:00Z"
93}
94```
95 
96### Version Entry (versions/{id}/v{n}.json)
97```json
98{
99  "version": 2,
100  "previousVersion": 1,
101  "path": "assets/banners/landing-pages/banner_claude-launch_hero-image_20251209_v2.png",
102  "changes": "Updated CTA button color to match brand refresh",
103  "createdAt": "2025-12-09T12:00:00Z",
104  "createdBy": "agent:ui-designer"
105}
106```
107 
108## Tagging System
109 
110### Standard Tags
111| Category | Values |
112|----------|--------|
113| status | draft, review, approved, archived |
114| platform | instagram, twitter, linkedin, facebook, youtube, email, web |
115| content-type | promotional, educational, brand, product, testimonial |
116| format | 1x1, 4x5, 9x16, 16x9, story, reel, banner |
117| source | imagen-4, veo-3, user-upload, canva, figma |
118 
119### Tag Usage
120- Each asset should have: status + platform + content-type
121- Optional: format, source, campaign
122 
123## File Organization Best Practices
124 
1251. **One file per variant** - Don't combine dark/light in one file
1262. **Source files separate** - Keep .psd/.fig in same structure
1273. **AI assets timestamped** - Auto-organize by generation date
1284. **Archive don't delete** - Move to `archived/` with date prefix
1295. **Large files external** - Videos > 100MB use cloud storage links
130 
131## Search Patterns
132 
133### By Type
134```bash
135# Find all banners
136ls assets/banners/**/*
137```
138 
139### By Campaign
140```bash
141# Find all assets for specific campaign
142grep -l "claude-launch" .assets/manifest.json
143```
144 
145### By Status
146```bash
147# Find approved assets only
148jq '.assets[] | select(.status == "approved")' .assets/manifest.json
149```
150 
151## Cleanup Workflow
152 
1531. Run `extract-colors.cjs` on new assets
1542. Validate against brand guidelines
1553. Update manifest.json with new entries
1564. Tag appropriately
1575. Remove duplicates/outdated versions
158