cli-jaw 0.1.0

package/skills_ref/hugging-face-model-trainer/scripts/unsloth_sft_example.py

@@ -0,0 +1,512 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "unsloth",
+#     "datasets",
+#     "trl==0.22.2",
+#     "huggingface_hub[hf_transfer]",
+#     "trackio",
+#     "tensorboard",
+#     "transformers==4.57.3",
+# ]
+# ///
+"""
+Fine-tune LLMs using Unsloth optimizations for ~60% less VRAM and 2x faster training.
+
+Supports epoch-based or step-based training with optional eval split.
+Default model: LFM2.5-1.2B-Instruct (Liquid Foundation Model).
+
+Epoch-based training (recommended for full datasets):
+    uv run unsloth_sft_example.py \
+        --dataset mlabonne/FineTome-100k \
+        --num-epochs 1 \
+        --eval-split 0.2 \
+        --output-repo your-username/model-finetuned
+
+Run on HF Jobs (1 epoch with eval):
+    hf jobs uv run unsloth_sft_example.py \
+        --flavor a10g-small --secrets HF_TOKEN --timeout 4h \
+        -- --dataset mlabonne/FineTome-100k \
+           --num-epochs 1 \
+           --eval-split 0.2 \
+           --output-repo your-username/model-finetuned
+
+Step-based training (for quick tests):
+    uv run unsloth_sft_example.py \
+        --dataset mlabonne/FineTome-100k \
+        --max-steps 500 \
+        --output-repo your-username/model-finetuned
+"""
+
+import argparse
+import logging
+import os
+import sys
+import time
+
+# Force unbuffered output for HF Jobs logs
+sys.stdout.reconfigure(line_buffering=True)
+sys.stderr.reconfigure(line_buffering=True)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def check_cuda():
+    """Check CUDA availability and exit if not available."""
+    import torch
+
+    if not torch.cuda.is_available():
+        logger.error("CUDA is not available. This script requires a GPU.")
+        logger.error("Run on a machine with a CUDA-capable GPU or use HF Jobs:")
+        logger.error(
+            "  hf jobs uv run unsloth_sft_example.py --flavor a10g-small ..."
+        )
+        sys.exit(1)
+    logger.info(f"CUDA available: {torch.cuda.get_device_name(0)}")
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Fine-tune LLMs with Unsloth optimizations",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Quick test run
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --max-steps 50 \\
+      --output-repo username/model-test
+
+  # Full training with eval
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --num-epochs 1 \\
+      --eval-split 0.2 \\
+      --output-repo username/model-finetuned
+
+  # With Trackio monitoring
+  uv run unsloth_sft_example.py \\
+      --dataset mlabonne/FineTome-100k \\
+      --num-epochs 1 \\
+      --output-repo username/model-finetuned \\
+      --trackio-space username/trackio
+        """,
+    )
+
+    # Model and data
+    parser.add_argument(
+        "--base-model",
+        default="LiquidAI/LFM2.5-1.2B-Instruct",
+        help="Base model (default: LiquidAI/LFM2.5-1.2B-Instruct)",
+    )
+    parser.add_argument(
+        "--dataset",
+        required=True,
+        help="Dataset in ShareGPT/conversation format (e.g., mlabonne/FineTome-100k)",
+    )
+    parser.add_argument(
+        "--output-repo",
+        required=True,
+        help="HF Hub repo to push model to (e.g., 'username/model-finetuned')",
+    )
+
+    # Training config
+    parser.add_argument(
+        "--num-epochs",
+        type=float,
+        default=None,
+        help="Number of epochs (default: None). Use instead of --max-steps.",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=None,
+        help="Training steps (default: None). Use for quick tests or streaming.",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=2,
+        help="Per-device batch size (default: 2)",
+    )
+    parser.add_argument(
+        "--gradient-accumulation",
+        type=int,
+        default=4,
+        help="Gradient accumulation steps (default: 4). Effective batch = batch-size * this",
+    )
+    parser.add_argument(
+        "--learning-rate",
+        type=float,
+        default=2e-4,
+        help="Learning rate (default: 2e-4)",
+    )
+    parser.add_argument(
+        "--max-seq-length",
+        type=int,
+        default=2048,
+        help="Maximum sequence length (default: 2048)",
+    )
+
+    # LoRA config
+    parser.add_argument(
+        "--lora-r",
+        type=int,
+        default=16,
+        help="LoRA rank (default: 16). Higher = more capacity but more VRAM",
+    )
+    parser.add_argument(
+        "--lora-alpha",
+        type=int,
+        default=16,
+        help="LoRA alpha (default: 16). Same as r per Unsloth recommendation",
+    )
+
+    # Logging
+    parser.add_argument(
+        "--trackio-space",
+        default=None,
+        help="HF Space for Trackio dashboard (e.g., 'username/trackio')",
+    )
+    parser.add_argument(
+        "--run-name",
+        default=None,
+        help="Custom run name for Trackio (default: auto-generated)",
+    )
+    parser.add_argument(
+        "--save-local",
+        default="unsloth-output",
+        help="Local directory to save model (default: unsloth-output)",
+    )
+
+    # Evaluation and data control
+    parser.add_argument(
+        "--eval-split",
+        type=float,
+        default=0.0,
+        help="Fraction of data for evaluation (0.0-0.5). Default: 0.0 (no eval)",
+    )
+    parser.add_argument(
+        "--num-samples",
+        type=int,
+        default=None,
+        help="Limit samples (default: None = use all)",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=3407,
+        help="Random seed for reproducibility (default: 3407)",
+    )
+    parser.add_argument(
+        "--merge-model",
+        action="store_true",
+        default=False,
+        help="Merge LoRA weights into base model before uploading (larger file, easier to use)",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    # Validate epochs/steps configuration
+    if not args.num_epochs and not args.max_steps:
+        args.num_epochs = 1
+        logger.info("Using default --num-epochs=1")
+
+    # Determine training duration display
+    if args.num_epochs:
+        duration_str = f"{args.num_epochs} epoch(s)"
+    else:
+        duration_str = f"{args.max_steps} steps"
+
+    print("=" * 70)
+    print("LLM Fine-tuning with Unsloth")
+    print("=" * 70)
+    print("\nConfiguration:")
+    print(f"  Base model:      {args.base_model}")
+    print(f"  Dataset:         {args.dataset}")
+    print(f"  Num samples:     {args.num_samples or 'all'}")
+    print(f"  Eval split:      {args.eval_split if args.eval_split > 0 else '(disabled)'}")
+    print(f"  Seed:            {args.seed}")
+    print(f"  Training:        {duration_str}")
+    print(f"  Batch size:      {args.batch_size} x {args.gradient_accumulation} = {args.batch_size * args.gradient_accumulation}")
+    print(f"  Learning rate:   {args.learning_rate}")
+    print(f"  LoRA rank:       {args.lora_r}")
+    print(f"  Max seq length:  {args.max_seq_length}")
+    print(f"  Output repo:     {args.output_repo}")
+    print(f"  Trackio space:   {args.trackio_space or '(not configured)'}")
+    print()
+
+    # Check CUDA before heavy imports
+    check_cuda()
+
+    # Enable fast transfers
+    os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
+
+    # Set Trackio space if provided
+    if args.trackio_space:
+        os.environ["TRACKIO_SPACE_ID"] = args.trackio_space
+        logger.info(f"Trackio dashboard: https://huggingface.co/spaces/{args.trackio_space}")
+
+    # Import heavy dependencies
+    from unsloth import FastLanguageModel
+    from unsloth.chat_templates import standardize_data_formats, train_on_responses_only
+    from datasets import load_dataset
+    from trl import SFTTrainer, SFTConfig
+    from huggingface_hub import login
+
+    # Login to Hub
+    token = os.environ.get("HF_TOKEN") or os.environ.get("hfjob")
+    if token:
+        login(token=token)
+        logger.info("Logged in to Hugging Face Hub")
+    else:
+        logger.warning("HF_TOKEN not set - model upload may fail")
+
+    # 1. Load model
+    print("\n[1/5] Loading model...")
+    start = time.time()
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=args.base_model,
+        max_seq_length=args.max_seq_length,
+        load_in_4bit=False,
+        load_in_8bit=False,
+        load_in_16bit=True,
+        full_finetuning=False,
+    )
+
+    # Add LoRA adapters
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=args.lora_r,
+        target_modules=["q_proj", "k_proj", "v_proj", "out_proj", "in_proj", "w1", "w2", "w3"],
+        lora_alpha=args.lora_alpha,
+        lora_dropout=0,
+        bias="none",
+        use_gradient_checkpointing="unsloth",
+        random_state=args.seed,
+        use_rslora=False,
+        loftq_config=None,
+    )
+    print(f"Model loaded in {time.time() - start:.1f}s")
+
+    # 2. Load and prepare dataset
+    print("\n[2/5] Loading dataset...")
+    start = time.time()
+
+    dataset = load_dataset(args.dataset, split="train")
+    print(f"  Dataset has {len(dataset)} total samples")
+
+    if args.num_samples:
+        dataset = dataset.select(range(min(args.num_samples, len(dataset))))
+        print(f"  Limited to {len(dataset)} samples")
+
+    # Auto-detect and normalize conversation column
+    for col in ["messages", "conversations", "conversation"]:
+        if col in dataset.column_names and isinstance(dataset[0][col], list):
+            if col != "conversations":
+                dataset = dataset.rename_column(col, "conversations")
+            break
+    dataset = standardize_data_formats(dataset)
+
+    # Apply chat template
+    def formatting_prompts_func(examples):
+        texts = tokenizer.apply_chat_template(
+            examples["conversations"],
+            tokenize=False,
+            add_generation_prompt=False,
+        )
+        # Remove BOS token to avoid duplicates
+        return {"text": [x.removeprefix(tokenizer.bos_token) for x in texts]}
+
+    dataset = dataset.map(formatting_prompts_func, batched=True)
+
+    # Split for evaluation if requested
+    if args.eval_split > 0:
+        split = dataset.train_test_split(test_size=args.eval_split, seed=args.seed)
+        train_data = split["train"]
+        eval_data = split["test"]
+        print(f"  Train: {len(train_data)} samples, Eval: {len(eval_data)} samples")
+    else:
+        train_data = dataset
+        eval_data = None
+
+    print(f"  Dataset ready in {time.time() - start:.1f}s")
+
+    # 3. Configure trainer
+    print("\n[3/5] Configuring trainer...")
+
+    # Calculate steps per epoch for logging/eval intervals
+    effective_batch = args.batch_size * args.gradient_accumulation
+    num_samples = len(train_data)
+    steps_per_epoch = num_samples // effective_batch
+
+    # Determine run name and logging steps
+    if args.run_name:
+        run_name = args.run_name
+    elif args.num_epochs:
+        run_name = f"unsloth-sft-{args.num_epochs}ep"
+    else:
+        run_name = f"unsloth-sft-{args.max_steps}steps"
+
+    if args.num_epochs:
+        logging_steps = max(1, steps_per_epoch // 10)
+        save_steps = max(1, steps_per_epoch // 4)
+    else:
+        logging_steps = max(1, args.max_steps // 20)
+        save_steps = max(1, args.max_steps // 4)
+
+    # Determine reporting backend
+    if args.trackio_space:
+        report_to = ["tensorboard", "trackio"]
+    else:
+        report_to = ["tensorboard"]
+
+    training_config = SFTConfig(
+        output_dir=args.save_local,
+        dataset_text_field="text",
+        per_device_train_batch_size=args.batch_size,
+        gradient_accumulation_steps=args.gradient_accumulation,
+        warmup_steps=5,
+        num_train_epochs=args.num_epochs if args.num_epochs else 1,
+        max_steps=args.max_steps if args.max_steps else -1,
+        learning_rate=args.learning_rate,
+        logging_steps=logging_steps,
+        optim="adamw_8bit",
+        weight_decay=0.01,
+        lr_scheduler_type="linear",
+        seed=args.seed,
+        max_length=args.max_seq_length,
+        report_to=report_to,
+        run_name=run_name,
+        push_to_hub=True,
+        hub_model_id=args.output_repo,
+        save_steps=save_steps,
+        save_total_limit=3,
+    )
+
+    # Add evaluation config if eval is enabled
+    if eval_data:
+        if args.num_epochs:
+            training_config.eval_strategy = "epoch"
+            print("  Evaluation enabled: every epoch")
+        else:
+            training_config.eval_strategy = "steps"
+            training_config.eval_steps = max(1, args.max_steps // 5)
+            print(f"  Evaluation enabled: every {training_config.eval_steps} steps")
+
+    trainer = SFTTrainer(
+        model=model,
+        tokenizer=tokenizer,
+        train_dataset=train_data,
+        eval_dataset=eval_data,
+        args=training_config,
+    )
+
+    # Train on responses only (mask user inputs)
+    trainer = train_on_responses_only(
+        trainer,
+        instruction_part="<|im_start|>user\n",
+        response_part="<|im_start|>assistant\n",
+    )
+
+    # 4. Train
+    print(f"\n[4/5] Training for {duration_str}...")
+    if args.num_epochs:
+        print(f"  (~{steps_per_epoch} steps/epoch, {int(steps_per_epoch * args.num_epochs)} total steps)")
+    start = time.time()
+
+    train_result = trainer.train()
+
+    train_time = time.time() - start
+    total_steps = train_result.metrics.get("train_steps", args.max_steps or steps_per_epoch * args.num_epochs)
+    print(f"\nTraining completed in {train_time / 60:.1f} minutes")
+    print(f"  Speed: {total_steps / train_time:.2f} steps/s")
+
+    # Print training metrics
+    train_loss = train_result.metrics.get("train_loss")
+    if train_loss:
+        print(f"  Final train loss: {train_loss:.4f}")
+
+    # Print eval results if eval was enabled
+    if eval_data:
+        print("\nRunning final evaluation...")
+        try:
+            eval_results = trainer.evaluate()
+            eval_loss = eval_results.get("eval_loss")
+            if eval_loss:
+                print(f"  Final eval loss: {eval_loss:.4f}")
+                if train_loss:
+                    ratio = eval_loss / train_loss
+                    if ratio > 1.5:
+                        print(f"  Warning: Eval loss is {ratio:.1f}x train loss - possible overfitting")
+                    else:
+                        print(f"  Eval/train ratio: {ratio:.2f} - model generalizes well")
+        except Exception as e:
+            print(f"  Warning: Final evaluation failed: {e}")
+            print("  Continuing to save model...")
+
+    # 5. Save and push
+    print("\n[5/5] Saving model...")
+
+    if args.merge_model:
+        print("Merging LoRA weights into base model...")
+        print(f"\nPushing merged model to {args.output_repo}...")
+        model.push_to_hub_merged(
+            args.output_repo,
+            tokenizer=tokenizer,
+            save_method="merged_16bit",
+        )
+        print(f"Merged model available at: https://huggingface.co/{args.output_repo}")
+    else:
+        model.save_pretrained(args.save_local)
+        tokenizer.save_pretrained(args.save_local)
+        print(f"Saved locally to {args.save_local}/")
+
+        print(f"\nPushing adapter to {args.output_repo}...")
+        model.push_to_hub(args.output_repo, tokenizer=tokenizer)
+        print(f"Adapter available at: https://huggingface.co/{args.output_repo}")
+
+    print("\n" + "=" * 70)
+    print("Done!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 1:
+        print("=" * 70)
+        print("LLM Fine-tuning with Unsloth")
+        print("=" * 70)
+        print("\nFine-tune language models with optional train/eval split.")
+        print("\nFeatures:")
+        print("  - ~60% less VRAM with Unsloth optimizations")
+        print("  - 2x faster training vs standard methods")
+        print("  - Epoch-based or step-based training")
+        print("  - Optional evaluation to detect overfitting")
+        print("  - Trains only on assistant responses (masked user inputs)")
+        print("\nEpoch-based training:")
+        print("\n  uv run unsloth_sft_example.py \\")
+        print("      --dataset mlabonne/FineTome-100k \\")
+        print("      --num-epochs 1 \\")
+        print("      --eval-split 0.2 \\")
+        print("      --output-repo your-username/model-finetuned")
+        print("\nHF Jobs example:")
+        print("\n  hf jobs uv run unsloth_sft_example.py \\")
+        print("      --flavor a10g-small --secrets HF_TOKEN --timeout 4h \\")
+        print("      -- --dataset mlabonne/FineTome-100k \\")
+        print("         --num-epochs 1 \\")
+        print("         --eval-split 0.2 \\")
+        print("         --output-repo your-username/model-finetuned")
+        print("\nFor full help: uv run unsloth_sft_example.py --help")
+        print("=" * 70)
+        sys.exit(0)
+
+    main()

package/skills_ref/imagegen/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: "imagegen"
+description: "Use when the user asks to generate or edit images via the OpenAI Image API (for example: generate image, edit/inpaint/mask, background removal or replacement, transparent background, product shots, concept art, covers, or batch variants); run the bundled CLI (`scripts/image_gen.py`) and require `OPENAI_API_KEY` for live calls."
+---
+
+
+# Image Generation Skill
+
+Generates or edits images for the current project (e.g., website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, infographics). Defaults to `gpt-image-1.5` and the OpenAI Image API, and prefers the bundled CLI for deterministic, reproducible runs.
+
+## When to use
+- Generate a new image (concept art, product shot, cover, website hero)
+- Edit an existing image (inpainting, masked edits, lighting or weather transformations, background replacement, object removal, compositing, transparent background)
+- Batch runs (many prompts, or many variants across prompts)
+
+## Decision tree (generate vs edit vs batch)
+- If the user provides an input image (or says “edit/retouch/inpaint/mask/translate/localize/change only X”) → **edit**
+- Else if the user needs many different prompts/assets → **generate-batch**
+- Else → **generate**
+
+## Workflow
+1. Decide intent: generate vs edit vs batch (see decision tree above).
+2. Collect inputs up front: prompt(s), exact text (verbatim), constraints/avoid list, and any input image(s)/mask(s). For multi-image edits, label each input by index and role; for edits, list invariants explicitly.
+3. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.
+4. Augment prompt into a short labeled spec (structure + constraints) without inventing new creative requirements.
+5. Run the bundled CLI (`scripts/image_gen.py`) with sensible defaults (see references/cli.md).
+6. For complex edits/generations, inspect outputs (open/view images) and validate: subject, style, composition, text accuracy, and invariants/avoid items.
+7. Iterate: make a single targeted change (prompt or mask), re-run, re-check.
+8. Save/return final outputs and note the final prompt + flags used.
+
+## Temp and output conventions
+- Use `tmp/imagegen/` for intermediate files (for example JSONL batches); delete when done.
+- Write final artifacts under `output/imagegen/` when working in this repo.
+- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.
+
+## Dependencies (install if missing)
+Prefer `uv` for dependency management.
+
+Python packages:
+```
+uv pip install openai pillow
+```
+If `uv` is unavailable:
+```
+python3 -m pip install openai pillow
+```
+
+## Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
+
+## Defaults & rules
+- Use `gpt-image-1.5` unless the user explicitly asks for `gpt-image-1-mini` or explicitly prefers a cheaper/faster model.
+- Assume the user wants a new image unless they explicitly ask for an edit.
+- Require `OPENAI_API_KEY` before any live API call.
+- Use the OpenAI Python SDK (`openai` package) for all API calls; do not use raw HTTP.
+- If the user requests edits, use `client.images.edit(...)` and include input images (and mask if provided).
+- Prefer the bundled CLI (`scripts/image_gen.py`) over writing new one-off scripts.
+- Never modify `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.
+- If the result isn’t clearly relevant or doesn’t satisfy constraints, iterate with small targeted prompt changes; only ask a question if a missing detail blocks success.
+
+## Prompt augmentation
+Reformat user prompts into a structured, production-oriented spec. Only make implicit details explicit; do not invent new requirements.
+
+## Use-case taxonomy (exact slugs)
+Classify each request into one of these buckets and keep the slug consistent across prompts and references.
+
+Generate:
+- photorealistic-natural — candid/editorial lifestyle scenes with real texture and natural lighting.
+- product-mockup — product/packaging shots, catalog imagery, merch concepts.
+- ui-mockup — app/web interface mockups that look shippable.
+- infographic-diagram — diagrams/infographics with structured layout and text.
+- logo-brand — logo/mark exploration, vector-friendly.
+- illustration-story — comics, children’s book art, narrative scenes.
+- stylized-concept — style-driven concept art, 3D/stylized renders.
+- historical-scene — period-accurate/world-knowledge scenes.
+
+Edit:
+- text-localization — translate/replace in-image text, preserve layout.
+- identity-preserve — try-on, person-in-scene; lock face/body/pose.
+- precise-object-edit — remove/replace a specific element (incl. interior swaps).
+- lighting-weather — time-of-day/season/atmosphere changes only.
+- background-extraction — transparent background / clean cutout.
+- style-transfer — apply reference style while changing subject/scene.
+- compositing — multi-image insert/merge with matched lighting/perspective.
+- sketch-to-render — drawing/line art to photoreal render.
+
+Quick clarification (augmentation vs invention):
+- If the user says “a hero image for a landing page”, you may add *layout/composition constraints* that are implied by that use (e.g., “generous negative space on the right for headline text”).
+- Do not introduce new creative elements the user didn’t ask for (e.g., adding a mascot, changing the subject, inventing brand names/logos).
+
+Template (include only relevant lines):
+```
+Use case: <taxonomy slug>
+Asset type: <where the asset will be used>
+Primary request: <user's main prompt>
+Scene/background: <environment>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D/etc>
+Composition/framing: <wide/close/top-down; placement>
+Lighting/mood: <lighting + mood>
+Color palette: <palette notes>
+Materials/textures: <surface details>
+Quality: <low/medium/high/auto>
+Input fidelity (edits): <low/high>
+Text (verbatim): "<exact text>"
+Constraints: <must keep/must avoid>
+Avoid: <negative constraints>
+```
+
+Augmentation rules:
+- Keep it short; add only details the user already implied or provided elsewhere.
+- Always classify the request into a taxonomy slug above and tailor constraints/composition/quality to that bucket. Use the slug to find the matching example in `references/sample-prompts.md`.
+- If the user gives a broad request (e.g., "Generate images for this website"), use judgment to propose tasteful, context-appropriate assets and map each to a taxonomy slug.
+- For edits, explicitly list invariants ("change only X; keep Y unchanged").
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+
+## Examples
+
+### Generation example (hero image)
+```
+Use case: stylized-concept
+Asset type: landing page hero
+Primary request: a minimal hero image of a ceramic coffee mug
+Style/medium: clean product photography
+Composition/framing: centered product, generous negative space on the right
+Lighting/mood: soft studio lighting
+Constraints: no logos, no text, no watermark
+```
+
+### Edit example (invariants)
+```
+Use case: precise-object-edit
+Asset type: product photo background replacement
+Primary request: replace the background with a warm sunset gradient
+Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark
+```
+
+## Prompting best practices (short list)
+- Structure prompt as scene -> subject -> details -> constraints.
+- Include intended use (ad, UI mock, infographic) to set the mode and polish level.
+- Use camera/composition language for photorealism.
+- Quote exact text and specify typography + placement.
+- For tricky words, spell them letter-by-letter and require verbatim rendering.
+- For multi-image inputs, reference images by index and describe how to combine them.
+- For edits, repeat invariants every iteration to reduce drift.
+- Iterate with single-change follow-ups.
+- For latency-sensitive runs, start with quality=low; use quality=high for text-heavy or detail-critical outputs.
+- For strict edits (identity/layout lock), consider input_fidelity=high.
+- If results feel “tacky”, add a brief “Avoid:” line (stock-photo vibe; cheesy lens flare; oversaturated neon; harsh bloom; oversharpening; clutter) and specify restraint (“editorial”, “premium”, “subtle”).
+
+More principles: `references/prompting.md`. Copy/paste specs: `references/sample-prompts.md`.
+
+## Guidance by asset type
+Asset-type templates (website assets, game assets, wireframes, logo) are consolidated in `references/sample-prompts.md`.
+
+## CLI + environment notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/image-api.md`
+- If network approvals / sandbox settings are getting in the way: `references/codex-network.md`
+
+## Reference map
+- **`references/cli.md`**: how to *run* image generation/edits/batches via `scripts/image_gen.py` (commands, flags, recipes).
+- **`references/image-api.md`**: what knobs exist at the API level (parameters, sizes, quality, background, edit-only fields).
+- **`references/prompting.md`**: prompting principles (structure, constraints/invariants, iteration patterns).
+- **`references/sample-prompts.md`**: copy/paste prompt recipes (generate + edit workflows; examples only).
+- **`references/codex-network.md`**: environment/sandbox/network-approval troubleshooting.

package/skills_ref/insecure-defaults/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "insecure-defaults",
+  "version": "1.0.0",
+  "description": "Detects insecure default configurations including hardcoded credentials, fallback secrets, weak authentication defaults, and dangerous values in production",
+  "author": {
+    "name": "Trail of Bits",
+    "email": "opensource@trailofbits.com",
+    "url": "https://github.com/trailofbits"
+  }
+}