scripts/README.md

# 🛠️ Pivoine Toolbelt

A collection of sophisticated Bash utility scripts for creative automation, asset management, and infrastructure control. These tools are designed with a focus on aesthetics, usability, and seamless integration with the Pivoine ecosystem.

## 🎨 Image & Creative Automation

### `img_api_generate.sh`
The primary interface for the Pivoine Image Generation API. Supports high-performance image creation with advanced control parameters.

*   **Models:** `mystic`, `flux-dev`, `flux-pro`, `seedream`.
*   **Features:**
    *   Custom aspect ratios (e.g., `square_1_1`, `widescreen_16_9`).
    *   Resolution control for Mystic model (1k, 2k, 4k).
    *   Seed reproducibility and styling injection.
    *   Integrated **FaceFusion** face swapping.
    *   Integrated **Real-ESRGAN** upscaling.
*   **Usage:** `./img_api_generate.sh -p "a cinematic portrait of a neon cyborg" --aspect-ratio widescreen_16_9 -m flux-pro`

### `css_color_palette.sh`
A zero-dependency color utility to generate comprehensive design tokens directly from the CLI. Generates tints, shades, and tones from a single base color.

### `mime_mp4_gif.sh`
High-quality video-to-GIF conversion utility optimized for web performance and visual fidelity.

---

## 📦 Asset & Model Management

### `artifact_civitai_download.sh` & `artifact_huggingface_download.sh`
Streamlined downloaders for AI models (Checkpoints, LoRAs, VAEs). 
*   Manages a central cache.
*   Automates symlinking to target application directories.
*   Verification mode to ensure link integrity.

### `artifact_git_download.sh` & `artifact_github_download.sh`
Sophisticated wrappers for managing repository-based artifacts and binary releases.

---

## ⚡ Infrastructure & Services

### `service_runpod_control.sh`
A beautiful CLI wrapper for managing RunPod GPU instances. Provides a unified interface for lifecycle management:
*   `create`, `remove`, `start`, `stop`, `status`.

### `jinja_template_render.sh`
Sophisticated Jinja2 template rendering engine. Ideal for generating configuration files, HTML emails, or boilerplate code using local JSON/YAML data.

---

## 🛠️ Developer Utilities

*   **`doc_bash_generate.sh`**: Automatic documentation generator for Bash scripts.
*   **`doc_rust_generate.sh`**: Documentation helper for Rust projects.
*   **`css_json_convert.sh`**: Bi-directional conversion between CSS variables and JSON objects.
*   **`artifact_postgres_export.sh`**: Styled database export and snapshot utility.

## 🚀 Getting Started

1.  **Dependencies**: Most scripts require `curl`, `jq`, and `base64`.
2.  **API Tokens**: For API-reliant scripts (like `img_api_generate.sh`), ensure your token is set in `~/.config/pivoine/token` or via environment variables.
3.  **Permissions**: Ensure scripts are executable:
    ```bash
    chmod +x *.sh
    ```

---
*Created with ✨ by the Pivoine Engineering Team.*