Composite headline + subtitle onto branded PNG templates OR directly onto client-supplied photos via the shared task_server pipeline. Local Pillow compositor — no FAL, zero render cost. Two modes (template_compose + photo_compose) behind one wrapper.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Composite headline + subtitle onto branded PNG templates OR directly onto client-supplied photos via the shared task_server pipeline. Local Pillow compositor — no FAL, zero render cost. Two modes (template_compose + photo_compose) behind one wrapper.
ONLY call scripts/design_tool.py. Do NOT invent curl commands; the script
handles auth, the brief shape, and the task lifecycle correctly.
NEVER cat ~/.hermes/secrets/.task_token — the wrapper reads the token from
$TASK_TOKEN_FILE without echoing it.
NEVER claim a template was rendered unless the wrapper printed
✓ completed — file://.... Then verify with ls -la <path> before telling the
user the file exists.
If the wrapper exits non-zero, tell the user the real error. Do not fall back
to pmax-image — they are different skills with different voice+brand intent.
When to use this skill
Brand-template posts with a consistent visual identity (logo, colors, typography)
GMB posts where the headline IS the post
Announcements / promos where a designer-made PNG template already exists
When you want deterministic output (same headline → same pixels)
When NOT to use this skill
Fresh AI-generated imagery → pmax-image (FAL)
Video / reels → pmax-video (FAL)
When no template PNG exists for the client → onboard one first, or use pmax-image
Backend
Same task_server + worker as pmax-image / pmax-video. One queue, one lifecycle.
Render path: render_mode="template_compose" + render_model="template/v1" → the
worker dispatches to TemplateComposeBackend (local Pillow) instead of FAL.
The moment --image is present, the wrapper flips to render_mode=photo_compose. The photo becomes the base layer, and the client-card brand_kit drives the overlay stack:
Contrast overlay (darken text zone for legibility) — optional per brand_kit
Logo (transparent PNG at configured corner) — optional per brand_kit
CTA pill (text + color + position) — optional per brand_kit
Rules:
Local path only in v1. URLs rejected.
--image path is canonicalized via ~/mem0-server/asset_intake.py to ~/mem0-server/assets/uploads/YYYY-MM/<client>/<hash>.<ext> before submission — deterministic dedupe.
Text-box coords scale from a 1080 reference canvas to the actual photo dimensions, so any aspect ratio works.
3) Override the template / template_id
design_tool.py generate --client mock --template-id lux-barbershop --headline "X"
Rare — prefer one template per client. Useful for A/B tests.
brand_kit schema (client card)
Add to ~/.hermes/profiles/pmax-dareen/clients/<slug>.yaml (or the equivalent
for Tarek / Mousa when they wire client-specific brand data):
brand_kit:contrast_overlay:enabled:truezone:bottom# top | bottom | left | right | fullstrength:0.55# 0.0-1.0 opacity of the dark rectanglelogo:path:/Users/majana-agent/mem0-server/assets/logos/<client>.pngposition:top-right# corners + top-center/bottom-center/centerscale:0.14# fraction of canvas widthcta:text:"Book Now"color:"#D4A85C"text_color:"#111111"position:bottom-rightfont_size:28
All three sub-blocks are optional. Missing block → overlay skipped silently. Missing logo file → skipped. Invalid position → defaults to top-left.
3) Fire and return (don't block on render)
design_tool.py generate --client mock --headline "X" --no-wait
# returns immediately with task_id; poll with `status`
4) List templates (honest view of what's actually wired)
design_tool.py list-templates
Output shows ✓ for templates with real PNGs installed, ⚠ PNG missing for
configs pointing at TODO placeholder names. Do not try to render against a
⚠ template — the worker will fail with FileNotFoundError.
5) Status / list
design_tool.py status 42
design_tool.py list --client mock --limit 5
Template onboarding (adding a new client)
Designer delivers 1080×1080 PNG (or any square; the compositor respects it).
Drop at ~/Projects/design-agent/templates/<client-slug>.png.
Verify with design_tool.py list-templates that the new client shows ✓.
Aspect ratio note
--aspect is NOT a template-compose option. Templates already have fixed
dimensions (the PNG defines them). Aspect-ratio routing is for FAL-based
image/video jobs. If you need a different aspect ratio, onboard a separate
template PNG at those dimensions.
Under the hood
design_tool.py is a thin wrapper — it calls task_server directly.
image_worker.py has a TemplateComposeBackend class that dynamically loads
~/Projects/design-agent/design_agent.py::compose_brief().
compose_brief() is a pure function: (brief: dict, asset_path: Path) -> str.
RTL/Arabic is supported if arabic_reshaper + python-bidi are installed.
COMPOSITOR_VERSION in design_agent.py bumps when text-rendering behavior changes.
Current live-template inventory (2026-04-18)
Only mock has a real PNG. The other 3 configs (kiddos-urgent-care,
lux-barbershop, nail-box) have pending-designer placeholder paths.
Honest status: template_compose plumbing is done; product-done is pending
real client templates being delivered by the designer.
