ai-job-search/docs/superpowers/plans/2026-07-12-pip-brand-pr.md

Pip Brand PR Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Ship the Pip mascot as the repo's brand: README header GIF, versioned brand assets, social preview card, and avatar, per docs/superpowers/specs/2026-07-11-mascot-brand-design.md.

Architecture: All brand assets live in assets/mascot/ with their source sheets and regeneration scripts. The README references one stable filename (pip_flight_loop.gif) so future mascot iterations never touch the README again. A stdlib-only unit test permanently guards against broken local image references in the README.

Tech Stack: Python 3 (Pillow + numpy + scipy for asset generation, stdlib only for the committed test), git, gh CLI.

Global Constraints

• Palette is exactly 7 colors: #2a9d8f #1f6f65 #e76f51 #969ba0 #ffffff #e63946 #22333b (tie shares #22333b)
• README-rendered GIF stays under 50 KB (current master: 30,138 bytes)
• Alt text for the mascot is exactly: Pip, the courier bird
• No text, logos, or tooling motifs inside the sprite itself
• The committed test must be stdlib-only (CI does not install Pillow)
• CI must stay green: python -m unittest discover and python tools/lint_skills.py pass after every task
• Work happens on the existing brand/mascot-pip branch (spec is already committed there)
• Source-of-truth files on this machine:
  • Master GIF: C:\Users\Bruger\Desktop\mascot_candidates\courier_flight_loop_v19_tie.gif (v19 = FINAL, user-approved: v8 white handling + blob removal with protected shell + thin outline repaint; v5-v18 and v20-v21 superseded)
  • ChatGPT tie sheet: C:\Users\Bruger\Downloads\ChatGPT Image 12. jul. 2026, 06.30.48.png
  • Gemini sheet: C:\Users\Bruger\Downloads\Gemini_Generated_Image_azwqj6azwqj6azwq (1).png
  • Retired flat sprites: C:\Users\Bruger\Desktop\mascot_candidates\{A_standing_courier,B_flying_delivery,C_envelope_hugger}.png
  • Assembly script: full v19 pipeline code reproduced in Task 1 Step 4

---

Task 1: Repo hygiene and brand assets in place

Files:

• Modify: .gitignore (append one block at end)
• Create: assets/mascot/pip_flight_loop.gif (copy of courier_flight_loop_v19_tie.gif)
• Create: assets/mascot/sources/chatgpt_tie_sheet.png
• Create: assets/mascot/sources/gemini_sheet.png
• Create: assets/mascot/reference/{A_standing_courier,B_flying_delivery,C_envelope_hugger}.png
• Create: assets/mascot/assemble_flight_loop.py
• Create: assets/mascot/README.md

Interfaces:

• Produces: assets/mascot/pip_flight_loop.gif — the stable path Task 2's README edit and Task 3's generator consume.

• Step 1: Add .superpowers/ to .gitignore

Append to the end of .gitignore:

# Brainstorm mockups (superpowers visual companion) - never ship
.superpowers/

• Step 2: Verify the ignore rule works

Run: git check-ignore -v .superpowers/foo.html Expected: prints a line ending in .superpowers/ — exit code 0

• Step 3: Copy assets into place

cd "C:/Users/Bruger/Desktop/github_local/ai-job-search"
mkdir -p assets/mascot/sources assets/mascot/reference
cp "C:/Users/Bruger/Desktop/mascot_candidates/courier_flight_loop_v19_tie.gif" assets/mascot/pip_flight_loop.gif
cp "C:/Users/Bruger/Downloads/ChatGPT Image 12. jul. 2026, 06.30.48.png" assets/mascot/sources/chatgpt_tie_sheet.png
cp "C:/Users/Bruger/Downloads/Gemini_Generated_Image_azwqj6azwqj6azwq (1).png" assets/mascot/sources/gemini_sheet.png
cp "C:/Users/Bruger/Desktop/mascot_candidates/A_standing_courier.png" assets/mascot/reference/
cp "C:/Users/Bruger/Desktop/mascot_candidates/B_flying_delivery.png" assets/mascot/reference/
cp "C:/Users/Bruger/Desktop/mascot_candidates/C_envelope_hugger.png" assets/mascot/reference/

• Step 4: Create assets/mascot/assemble_flight_loop.py

Full script (the session's v19 pipeline with repo-relative paths):

"""Regenerate pip_flight_loop.gif from sources/chatgpt_tie_sheet.png.

Pipeline: 2D-cluster the sheet into 6 birds, snap every pixel to the 7-color
brand palette, order frames by wing centroid (no per-frame rescaling),
anchor on the beak, flood-fill edge-connected background to transparent.
Requires: pillow, numpy, scipy (maintainer tooling; not needed by CI).
"""
from pathlib import Path
from PIL import Image
import numpy as np
from scipy import ndimage

HERE = Path(__file__).parent
SHEET = HERE / "sources" / "chatgpt_tie_sheet.png"
OUT_GIF = HERE / "pip_flight_loop.gif"

PAL = np.array([
    (42, 157, 143), (31, 111, 101), (231, 111, 81), (150, 155, 160),
    (255, 255, 255), (230, 57, 70), (34, 51, 59),
], dtype=int)
TRANSPARENT = 7
CANVAS = 560

im = Image.open(SHEET).convert("RGB")
a_full = np.asarray(im).astype(int)
nonwhite_full = (a_full < 245).any(axis=2)

# 2D clustering: dilate to glue beak tips, label, keep 6 largest, sort by x
dil = ndimage.binary_dilation(nonwhite_full, iterations=2)
lab2, n2 = ndimage.label(dil)
sizes = ndimage.sum(dil, lab2, range(1, n2 + 1))
keep = np.argsort(sizes)[::-1][:6] + 1
comps = []
for k in keep:
    mask = (lab2 == k) & nonwhite_full
    ys, xs = np.where(mask)
    comps.append(dict(mask=mask, x0=xs.min(), x1=xs.max(), y0=ys.min(), y1=ys.max(), cx=xs.mean()))
comps.sort(key=lambda d: d["cx"])
assert len(comps) == 6, f"expected 6 birds, found {len(comps)}"

def snap(arr):
    d = ((arr[:, :, None, :] - PAL[None, None, :, :]) ** 2).sum(-1)
    return PAL[d.argmin(-1)].astype(np.uint8)

cells = []
for comp in comps:
    pad = 8
    y0, y1 = max(0, comp["y0"] - pad), comp["y1"] + pad
    x0, x1 = max(0, comp["x0"] - pad), comp["x1"] + pad
    sub = a_full[y0:y1, x0:x1].copy()
    submask = comp["mask"][y0:y1, x0:x1]
    sub[~submask] = (255, 255, 255)
    cells.append(snap(sub))

def color_mask(arr, ci, tol=10):
    return np.abs(arr.astype(int) - PAL[ci]).sum(-1) < tol

infos = []
for i, c in enumerate(cells):
    coral = color_mask(c, 2)
    lab, n = ndimage.label(coral)
    best, besty = None, 10 ** 9
    for k in range(1, n + 1):
        ys, xs = np.where(lab == k)
        if len(ys) < 80:
            continue
        if ys.mean() < besty:
            besty, best = ys.mean(), (xs, ys)
    bx, by = best[0].mean(), best[1].mean()
    dteal = color_mask(c, 1)
    wing_c = float(np.where(dteal)[0].mean()) if dteal.sum() else by
    infos.append(dict(i=i, beak=(bx, by), area=len(best[0]), wing_c=wing_c))

for d_ in infos:
    # birds in the sheet are size-consistent (within 5%); rescaling by noisy
    # beak measurements caused a visible zoom pulse in an earlier build
    d_["scale"] = 1.0
    d_["wing_rel"] = d_["wing_c"] - d_["beak"][1]

order_sorted = sorted(infos, key=lambda d: d["wing_rel"])
seq = [order_sorted[0], order_sorted[2], order_sorted[4], order_sorted[5], order_sorted[3], order_sorted[1]]

p_frames = []
for d_ in seq:
    c = cells[d_["i"]]
    h, w = c.shape[:2]
    sc = d_["scale"]
    c2 = np.asarray(Image.fromarray(c).resize((int(w * sc), int(h * sc)), Image.NEAREST))
    beak = (d_["beak"][0] * sc, d_["beak"][1] * sc)
    canvas = np.full((CANVAS, CANVAS, 3), 255, dtype=np.uint8)
    tx, ty = int(CANVAS * 0.72), int(CANVAS * 0.38)
    px, py = int(tx - beak[0]), int(ty - beak[1])
    H2, W2 = c2.shape[:2]
    x0, y0 = max(0, px), max(0, py)
    x1, y1 = min(CANVAS, px + W2), min(CANVAS, py + H2)
    canvas[y0:y1, x0:x1] = c2[y0 - py:y0 - py + (y1 - y0), x0 - px:x0 - px + (x1 - x0)]

    nonwhite = (canvas < 250).any(axis=2)
    lab, n = ndimage.label(nonwhite)
    for k in range(1, n + 1):
        ys, xs = np.where(lab == k)
        cols = canvas[ys, xs].astype(int)
        is_gray = (np.abs(cols - PAL[3]).sum(-1) < 60).mean() > 0.6
        if len(ys) < 400 and ys.mean() < 300 and is_gray:
            canvas[ys, xs] = (255, 255, 255)
            nonwhite[ys, xs] = False

    d2 = ((canvas.astype(int)[:, :, None, :] - PAL[None, None, :, :]) ** 2).sum(-1)
    idx = d2.argmin(-1).astype(np.uint8)
    white = ~nonwhite
    wlab, wn = ndimage.label(white)
    border = set(wlab[0, :]) | set(wlab[-1, :]) | set(wlab[:, 0]) | set(wlab[:, -1])
    border.discard(0)
    idx[np.isin(wlab, list(border))] = TRANSPARENT
    # enclosed white pockets: classify by boundary composition. The chest patch
    # always borders light teal (body interior); the envelope face is >=70%
    # gray/red; true background pockets (between legs, body-envelope gap) are
    # neither. NOTE: do not use outline/dark-teal ratios here - anti-aliased
    # white-to-outline edges quantize to gray and poison those ratios.
    for wl in range(1, wn + 1):
        if wl in border:
            continue
        comp = wlab == wl
        ring = ndimage.binary_dilation(comp, iterations=2) & ~comp & nonwhite
        ridx = idx[ring]
        if len(ridx) == 0:
            continue
        teal = (ridx == 0).sum() / len(ridx)                # light teal only
        envelope = np.isin(ridx, [3, 5]).sum() / len(ridx)  # gray, red
        if teal >= 0.08:
            continue  # chest: real content
        if envelope >= 0.70:
            continue  # envelope face: real content, keep whole. (A border-clip
            # was tried here to split merged face+gap components; it misfit
            # tilted envelopes and bit into the face. The merged white reads
            # fine as-is - do not reintroduce clipping.)
        idx[comp] = TRANSPARENT
    # targeted art cleanup: the source sheet has one large outlined teal blob
    # (a vestigial appendage) drawn into the body-envelope gap of one frame.
    # Only fragments >=100px qualify - smaller teal fragments are legitimate
    # pixel-art texture, and generic cleanup rules damage the tie and feet.
    bird_mask = np.isin(idx, [0, 1])
    blab, bn = ndimage.label(bird_mask)
    if bn > 1:
        bsizes = ndimage.sum(bird_mask, blab, range(1, bn + 1))
        bmain = int(np.argmax(bsizes)) + 1
        gray_mask = idx == 3
        glab, gn = ndimage.label(gray_mask)
        a_fit, b_fit = 0.0, 10 ** 6
        if gn:
            gsizes = ndimage.sum(gray_mask, glab, range(1, gn + 1))
            env_gray = glab == (int(np.argmax(gsizes)) + 1)
            cols = np.where(env_gray.any(axis=0))[0]
            tops = env_gray.argmax(axis=0)[cols].astype(float)
            med = np.median(tops)
            good = np.abs(tops - med) <= 20
            if good.sum() >= 10:
                a_fit, b_fit = np.polyfit(cols[good], tops[good], 1)
            else:
                a_fit, b_fit = 0.0, med
        for bk in range(1, bn + 1):
            if bk == bmain or not (100 <= bsizes[bk - 1] < 600):
                continue
            ys3, xs3 = np.where(blab == bk)
            cy, cx = ys3.mean(), xs3.mean()
            border_here = a_fit * cx + b_fit
            if not (border_here - 55 <= cy < border_here):
                continue
            fmask = blab == bk
            ring = ndimage.binary_dilation(fmask, iterations=2) & ~fmask
            if not ring.any() or (idx[ring] == 6).mean() < 0.40:
                continue
            # erase the blob's own outline ring, but protect outline pixels
            # that belong to the body, chest, tie, or feet (anything near the
            # main structures) - an unprotected shell bit the body outline
            protected = ndimage.binary_dilation(
                (blab == bmain) | (idx == 4) | (idx == 2), iterations=2)
            shell = ndimage.binary_dilation(fmask, iterations=3) & (idx == 6) & ~protected
            erased = fmask | shell
            idx[fmask] = TRANSPARENT
            idx[shell] = TRANSPARENT
            # repair: the blob's boundary doubled as the local body outline, so
            # erasing it exposes bare chest white to the background. Repaint the
            # exposed content edge (white/teal within the wound area, near the
            # new transparency) as outline so the bird's underside stays closed.
            near_wound = ndimage.binary_dilation(erased, iterations=6)
            transp = idx == TRANSPARENT
            near_gap = ndimage.binary_dilation(transp, iterations=6)
            repaint = near_wound & near_gap & np.isin(idx, [0, 1, 4])
            idx[repaint] = 6
    p = Image.fromarray(idx, mode="P")
    palette = PAL.astype(np.uint8).flatten().tolist() + [255, 0, 255]
    p.putpalette(palette + [0] * (768 - len(palette)))
    p.info["transparency"] = TRANSPARENT
    p_frames.append(p)

p_frames[0].save(OUT_GIF, save_all=True, append_images=p_frames[1:],
                 duration=110, loop=0, disposal=2, transparency=TRANSPARENT, optimize=False)
print(f"wrote {OUT_GIF} ({OUT_GIF.stat().st_size} bytes)")
assert OUT_GIF.stat().st_size < 50_000, "README asset must stay under 50 KB"

• Step 5: Create assets/mascot/README.md

# Pip, the courier bird

Brand assets for the project mascot. Design spec:
[`docs/superpowers/specs/2026-07-11-mascot-brand-design.md`](../../docs/superpowers/specs/2026-07-11-mascot-brand-design.md).

| File | Purpose |
|---|---|
| `pip_flight_loop.gif` | The animated brand mark (README header). 6 frames, transparent, <50 KB. |
| `pip_avatar.png` | Static square avatar (repo/social use). |
| `social_preview.png` | 1280x640 card for GitHub Settings -> Social preview. |
| `sources/` | AI-generated sprite sheets the frames were cut from. |
| `reference/` | Retired flat-style sprites, kept as palette reference. |
| `assemble_flight_loop.py` | Regenerates the GIF from the tie sheet (pillow+numpy+scipy). |
| `make_brand_assets.py` | Regenerates avatar + social card from the GIF (pillow). |

Palette (exactly 7 colors): `#2a9d8f` `#1f6f65` `#e76f51` `#969ba0` `#ffffff` `#e63946` `#22333b`.
The sprite never carries text or logos. Alt text is always "Pip, the courier bird".

• Step 6: Verify the regeneration script reproduces the GIF

Run: cd assets/mascot && python assemble_flight_loop.py Expected: wrote ...pip_flight_loop.gif (~30000 bytes), no assertion error. Then run git diff --stat assets/mascot/pip_flight_loop.gif — if the file changed byte-wise but a re-run is stable, that is fine (the copy in Step 3 and the regenerated file must simply both be valid; keep the regenerated one).

• Step 7: Run the existing suite (nothing should break)

Run: python -m unittest discover && python tools/lint_skills.py Expected: OK and lint_skills: OK

• Step 8: Commit

git add .gitignore assets/
git commit -m "feat(brand): add Pip mascot assets and regeneration pipeline"

---

Task 2: README header swap + permanent image-reference guard

Files:

• Create: tests/test_readme_assets.py
• Modify: README.md:1-3
• Delete: claude_animation.gif

Interfaces:

• Consumes: assets/mascot/pip_flight_loop.gif from Task 1.

• Produces: nothing downstream; the test becomes a permanent CI guard.

• Step 1: Write the guard test

Create tests/test_readme_assets.py (stdlib only — CI installs no packages):

"""Every local image referenced by README.md must exist in the repo.

A broken header image on the repo landing page is a silent, high-visibility
failure; this guard turns it into a red CI run instead.
"""
import re
import unittest
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent
README = REPO / "README.md"

IMG_SRC = re.compile(r'<img[^>]+src="([^"]+)"')
MD_IMG = re.compile(r"!\[[^\]]*\]\(([^)\s]+)")


class ReadmeImageReferences(unittest.TestCase):
    def _local_refs(self):
        text = README.read_text(encoding="utf-8")
        refs = IMG_SRC.findall(text) + MD_IMG.findall(text)
        return [r for r in refs if not r.startswith(("http://", "https://"))]

    def test_readme_exists_and_references_at_least_one_local_image(self):
        refs = self._local_refs()
        self.assertGreaterEqual(len(refs), 1, "README lost its mascot header image")

    def test_all_local_image_references_resolve(self):
        for ref in self._local_refs():
            with self.subTest(ref=ref):
                self.assertTrue((REPO / ref).is_file(), f"README references missing file: {ref}")


if __name__ == "__main__":
    unittest.main()

• Step 2: Run it — it must pass against the CURRENT README (claude_animation.gif still exists)

Run: python -m unittest tests.test_readme_assets -v Expected: 2 tests PASS (this proves the test works before the swap; it will catch a bad path after the swap)

• Step 3: Swap the README header

In README.md, replace exactly:

  <img src="claude_animation.gif" alt="AI Job Search Assistant" width="200">

with:

  <img src="assets/mascot/pip_flight_loop.gif" alt="Pip, the courier bird" width="200">

• Step 4: Delete the old placeholder GIF

Run: git rm claude_animation.gif

• Step 5: Confirm no stale references remain

Run: grep -rn "claude_animation" --include="*.md" --include="*.yml" --include="*.tex" . Expected: no matches (the only reference was README.md line 2)

• Step 6: Re-run the guard test — now validating the NEW path

Run: python -m unittest tests.test_readme_assets -v Expected: 2 tests PASS. (If Step 3's path had a typo, this fails — that is the guard working.)

• Step 7: Full suite + lint

Run: python -m unittest discover && python tools/lint_skills.py Expected: all pass

• Step 8: Commit

git add README.md tests/test_readme_assets.py
git commit -m "feat(brand): Pip takes over the README header"

---

Task 3: Avatar and social preview card generator

Files:

• Create: assets/mascot/make_brand_assets.py
• Create: assets/mascot/pip_avatar.png (generated)
• Create: assets/mascot/social_preview.png (generated)

Interfaces:

• Consumes: assets/mascot/pip_flight_loop.gif from Task 1.

• Produces: pip_avatar.png (512x512 RGBA) and social_preview.png (1280x640 RGB) for the manual upload steps in Task 4.

• Step 1: Write the generator

Create assets/mascot/make_brand_assets.py:

"""Generate pip_avatar.png (512x512) and social_preview.png (1280x640)
from pip_flight_loop.gif. Requires pillow (maintainer tooling, not CI).

Layout rule for the card (the old draft's bug was text/mascot overlap):
mascot occupies x < 500; text starts at x = 540; an assertion enforces
that the widest text line fits inside the canvas.
"""
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont

HERE = Path(__file__).parent
GIF = HERE / "pip_flight_loop.gif"

INK = (34, 51, 59)        # 22333b
GRAY = (120, 126, 133)
SEAL = (230, 57, 70)      # e63946
WORDMARK = "ai-job-search"
TAGLINE = "job search that runs on your machine"

def best_frame(gif_path, frame_index=0):
    g = Image.open(gif_path)
    g.seek(frame_index)
    return g.convert("RGBA")

def find_font(size):
    candidates = [
        r"C:\Windows\Fonts\consolab.ttf",   # Consolas Bold
        r"C:\Windows\Fonts\consola.ttf",
        "/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf",
    ]
    for c in candidates:
        if Path(c).exists():
            return ImageFont.truetype(c, size)
    return ImageFont.load_default()

def make_avatar():
    frame = best_frame(GIF, 0)  # first frame: wing raised, reads best square
    bbox = frame.getbbox()
    crop = frame.crop(bbox)
    side = max(crop.size) + 60
    canvas = Image.new("RGBA", (side, side), (0, 0, 0, 0))
    canvas.paste(crop, ((side - crop.width) // 2, (side - crop.height) // 2), crop)
    canvas = canvas.resize((512, 512), Image.NEAREST)
    out = HERE / "pip_avatar.png"
    canvas.save(out)
    print(f"wrote {out}")

def make_card():
    W, H = 1280, 640
    card = Image.new("RGB", (W, H), (255, 255, 255))
    draw = ImageDraw.Draw(card)

    frame = best_frame(GIF, 0)
    bbox = frame.getbbox()
    crop = frame.crop(bbox)
    target_h = 420
    scale = target_h / crop.height
    crop = crop.resize((int(crop.width * scale), target_h), Image.NEAREST)
    mascot_x = 90
    assert mascot_x + crop.width <= 500, "mascot must stay left of x=500"
    card.paste(crop, (mascot_x, (H - crop.height) // 2), crop)

    f_big = find_font(72)
    f_small = find_font(32)
    tx = 540
    draw.text((tx, 240), WORDMARK, font=f_big, fill=INK)
    wm_w = draw.textlength(WORDMARK, font=f_big)
    tag_w = draw.textlength(TAGLINE, font=f_small)
    assert tx + max(wm_w, tag_w) <= W - 40, "text overflows card"
    draw.text((tx, 340), TAGLINE, font=f_small, fill=GRAY)
    # seal-red accent: small dot echoing the envelope seal
    draw.ellipse((tx + 2, 402, tx + 22, 422), fill=SEAL)
    draw.text((tx + 34, 400), "free & open source", font=f_small, fill=GRAY)

    out = HERE / "social_preview.png"
    card.save(out)
    print(f"wrote {out}")

if __name__ == "__main__":
    make_avatar()
    make_card()

• Step 2: Run it

Run: cd assets/mascot && python make_brand_assets.py Expected: wrote ...pip_avatar.png and wrote ...social_preview.png, no assertion errors

• Step 3: Visually inspect both outputs

Read assets/mascot/pip_avatar.png and assets/mascot/social_preview.png with the Read tool. Check: avatar is centered with clear margins, transparent corners; card has no mascot/text overlap, wordmark and tagline legible, seal-red dot present. Iterate on coordinates if anything overlaps — the assertions catch overflow, only aesthetics need eyes.

• Step 4: Full suite + lint

Run: python -m unittest discover && python tools/lint_skills.py Expected: all pass

• Step 5: Commit

git add assets/mascot/make_brand_assets.py assets/mascot/pip_avatar.png assets/mascot/social_preview.png
git commit -m "feat(brand): generate Pip avatar and social preview card"

---

Task 4: Final verification, push, and PR

Files:

• No file changes; verification, push, PR creation, and documented manual steps.

Interfaces:

• Consumes: all commits on brand/mascot-pip from Tasks 1-3 plus the two spec commits already on the branch.

• Step 1: Full local verification

Run: python -m unittest discover -v && python tools/lint_skills.py && python tools/security_guards.py Expected: all green (security guards must pass — this PR touches .gitignore, which the guard inspects)

• Step 2: Review the full diff

Run: git diff master...brand/mascot-pip --stat Expected: spec + plan docs, .gitignore (+2 lines), assets/mascot/* added, README.md (1 line changed), claude_animation.gif deleted, tests/test_readme_assets.py added. Nothing else.

• Step 3: Push and open the PR

git push -u origin brand/mascot-pip
gh pr create --title "brand: meet Pip, the courier bird" --body "$(cat <<'EOF'
Replaces the placeholder header animation with the project's own mascot: **Pip**, a pixel-art courier bird delivering your applications (now with a tie - dressed for the interviews it books you).

- README header: transparent 6-frame flight loop, 30 KB, renders on light and dark themes
- assets/mascot/: master GIF, source sheets, retired palette-reference sprites, and the full regeneration pipeline (palette-snap to exactly 7 brand colors, beak-anchored alignment, measured flap-cycle ordering)
- tests/test_readme_assets.py: stdlib-only CI guard - every local image the README references must exist
- .gitignore: excludes .superpowers/ brainstorm artifacts
- Design spec included: docs/superpowers/specs/2026-07-11-mascot-brand-design.md

No behavior changes to any skill, command, or CLI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Expected: PR URL printed. Wait for CI to pass before merging.

• Step 4: Document the two manual steps for the maintainer

These cannot be done via git and are Mads-manual:

1. Social preview: GitHub repo → Settings → General → Social preview → upload assets/mascot/social_preview.png
2. Avatar (optional): use assets/mascot/pip_avatar.png wherever a square mark is needed (e.g. a future org account; personal GitHub avatar stays personal)

• Step 5: After merge (separate, do not merge unilaterally)

Merging the PR is the maintainer's call in this repo's normal flow. After merge, verify the rendered README on github.com in both light and dark themes, then delete the local brand/mascot-pip branch.

---

Self-Review (completed)

• Spec coverage: palette lock (Task 1 script + assets README), flight-loop GIF as README header with correct alt text (Task 2), social card with wordmark + tagline (Task 3), avatar (Task 3), seal-red echo (Task 3 card dot), .superpowers/ gitignore (Task 1), assets/mascot/ layout with sources/reference/scripts (Task 1), <50 KB budget (Task 1 assertion), both-themes render check (Task 4 Step 5). Out-of-scope items (pose redraws, Ko-fi copy, donation execution) correctly absent.
• Placeholder scan: no TBDs; all code complete.
• Type consistency: pip_flight_loop.gif path is identical across Tasks 1, 2, 3; palette constants match the spec hexes.