mycopunk-swag/docs/workflow.md

# Mycopunk Workflow Guide

This document describes the end-to-end workflow for creating, managing, and fulfilling mycopunk merchandise.

## Overview

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Design    │ →  │   Export    │ →  │   Publish   │ →  │  Fulfill    │
│  (Inkscape) │    │   (CLI)     │    │   (POD)     │    │  (Orders)   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
```

## Phase 1: Design Creation

### 1.1 Create Design Scaffold

```bash
# Create a new sticker design
mycopunk design new stickers/mycelium-mandala --template=sticker-4x4
```

This creates:
```
designs/stickers/mycelium-mandala/
├── mycelium-mandala.svg    # Source file
├── metadata.yaml           # Configuration
└── exports/                # Output directory
```

### 1.2 Design in Inkscape

Open the SVG file in Inkscape:

```bash
inkscape designs/stickers/mycelium-mandala/mycelium-mandala.svg
```

**Design Guidelines:**
- Work at the specified canvas size (e.g., 1200×1200 px for 4×4" sticker)
- Use sRGB color profile
- Keep important elements away from edges (safe zone)
- Add 1/16" bleed if design touches edges
- Save frequently!

### 1.3 Configure Metadata

Edit `metadata.yaml`:

```yaml
name: "Mycelium Mandala"
slug: mycelium-mandala
description: "Sacred geometry inspired by fungal networks"
tags: [mycelium, mandala, sacred-geometry, nature]
created: 2025-01-24
author: jeff

source:
  file: mycelium-mandala.svg
  format: svg
  dimensions:
    width: 1200
    height: 1200
  dpi: 300
  color_profile: sRGB

products:
  - type: sticker
    provider: prodigi
    sku: GLOBAL-STI-KIS-4X4
    variants: [matte, gloss]
    retail_price: 4.50

  - type: sticker
    provider: printful
    sku: 358
    variants: [white]
    retail_price: 4.50

status: draft  # Change to 'active' when ready
```

---

## Phase 2: Export & Validate

### 2.1 Export to Print-Ready Files

```bash
mycopunk design export stickers/mycelium-mandala
```

Output:
```
✓ Exported: designs/stickers/mycelium-mandala/exports/300dpi/mycelium-mandala.png
  Size: 245.3 KB
  Dimensions: 1200×1200 px
```

### 2.2 Validate Design

```bash
mycopunk design validate stickers/mycelium-mandala
```

Output:
```
Validating: Mycelium Mandala

  ✓ Metadata field 'name' present
  ✓ Metadata field 'slug' present
  ✓ Metadata field 'source' present
  ✓ Metadata field 'products' present
  ✓ Metadata field 'status' present
  ✓ Source file exists: mycelium-mandala.svg
  ✓ Dimensions correct: 1200×1200
  ✓ Products configured: 2

✓ Validation passed
```

### 2.3 Generate Local Mockups (Optional)

For quick previews without API calls:

```bash
./scripts/generate-mockups.sh stickers/mycelium-mandala
```

---

## Phase 3: Publish to POD

### 3.1 Test in Sandbox First

Always test with sandbox credentials:

```bash
mycopunk product create stickers/mycelium-mandala --provider=prodigi --sandbox
```

### 3.2 Update Status

Once satisfied, update the design status:

```yaml
# In metadata.yaml
status: active
```

### 3.3 Create Production Product

```bash
# Ensure MYCOPUNK_ENV=production or use live API keys
mycopunk product create stickers/mycelium-mandala --provider=prodigi
```

### 3.4 Generate Production Mockups

```bash
mycopunk mockup generate stickers/mycelium-mandala --all
```

---

## Phase 4: Selling & Fulfillment

### Option A: Use POD Storefronts

Both Printful and Prodigi integrate with:
- Etsy
- Shopify
- WooCommerce
- Amazon

Connect your accounts in their dashboards.

### Option B: Custom Shop (Phase 5)

Build your own storefront (see architecture in plan).

### Order Flow

```
Customer Order → Payment → API Call to POD → Fulfillment → Shipping
```

---

## Batch Operations

### Export All Active Designs

```bash
mycopunk batch export --status=active
```

### Push All to POD

```bash
mycopunk batch push --status=active --provider=prodigi
```

### Generate Price Report

```bash
mycopunk report pricing > pricing.csv
```

---

## File Organization Best Practices

### Design Directory Structure

```
designs/
├── stickers/
│   ├── mycelium-mandala/
│   │   ├── mycelium-mandala.svg    # Source (edit this)
│   │   ├── mycelium-mandala.xcf    # GIMP working file (optional)
│   │   ├── metadata.yaml           # Configuration
│   │   ├── reference/              # Inspiration images (optional)
│   │   └── exports/
│   │       ├── 300dpi/
│   │       │   └── mycelium-mandala.png
│   │       └── mockups/
│   │           ├── sticker-mockup.png
│   │           └── product-photo.jpg
│   └── spore-spiral/
│       └── ...
├── shirts/
│   └── network-tee/
│       └── ...
└── misc/
    ├── patches/
    ├── pins/
    └── zines/
```

### Naming Conventions

- **Slugs**: lowercase, hyphen-separated (e.g., `mycelium-mandala`)
- **Files**: Match slug (e.g., `mycelium-mandala.svg`)
- **Categories**: Plural (e.g., `stickers/`, `shirts/`)

---

## Git Workflow

### Committing Designs

```bash
# Add new design
git add designs/stickers/mycelium-mandala/

# Don't commit exports (they're gitignored)
# They can be regenerated with mycopunk design export

git commit -m "feat(stickers): add mycelium mandala design"
```

### Branching Strategy

```
main           # Production-ready designs
└── dev        # Work in progress
    └── feature/new-sticker-pack
```

---

## Troubleshooting

### Export Fails

**Problem**: Inkscape export produces error

**Solution**:
1. Check Inkscape is installed: `which inkscape`
2. Verify SVG is valid: open in Inkscape GUI
3. Check file permissions

### Validation Warnings

**Problem**: "Low resolution" warning

**Solution**: Ensure source SVG canvas matches target dimensions at 300 DPI

**Problem**: "No exported PNG found"

**Solution**: Run `mycopunk design export <path>` first

### API Errors

**Problem**: "401 Unauthorized"

**Solution**: Check API keys in `config/.env`

**Problem**: "Invalid SKU"

**Solution**: Sync catalog and verify SKU exists:
```bash
./scripts/sync-catalog.sh prodigi
jq '.products[] | .sku' .cache/catalogs/prodigi-catalog.json | grep -i sticker
```

---

## Quick Reference

| Task | Command |
|------|---------|
| New design | `mycopunk design new <path> --template=<t>` |
| List designs | `mycopunk design list` |
| Export design | `mycopunk design export <path>` |
| Validate design | `mycopunk design validate <path>` |
| Create product | `mycopunk product create <path> --provider=<p>` |
| Push updates | `mycopunk product push <path>` |
| Generate mockups | `mycopunk mockup generate <path>` |
| Batch export | `mycopunk batch export --type=<t>` |