@topy-ai/maggie 0.8.0 → 0.8.2

package/bundled-tools/runtime/spirit_base.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""ONEMAN sprite system — the reusable animated status-sprite basic set.
+
+Every ONEMAN agent (Core or Service) shares ONE visual language: a 17x17 flat
+pixel motif, a fixed semantic palette tinted by the agent's accent, a catalog of
+32 common states, and a vocabulary of animation primitives. Give this generator
+a Motif (the agent's mark) + an accent colour and it emits the whole set in a
+consistent style: an animated PNG frame strip per state, a still SVG per state,
+a combined overview sheet, and states.json (frames + fps) to drive CSS/canvas.
+
+The ONEMAN mark (a blocky O ring + central 1 bar, accent #ff1212 = topy.ai) is
+the default motif. A new agent reuses everything here and supplies only its own
+motif grid + accent, so the whole roster animates and reads identically.
+
+Usage:
+    python3 sprite_system.py                      # regenerate the ONEMAN set
+    from sprite_system import Motif, generate      # build another agent's set
+    generate(Motif.oneman(), accent="#ff1212", out="oneman", title="ONEMAN")
+
+PIL only (no cairosvg).
+"""
+from __future__ import annotations
+import json, math, os
+from PIL import Image, ImageDraw
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+OUT_BASE = HERE
+
+# ---------------------------------------------------------------- palette ----
+def _rgb(h): h=h.lstrip("#"); return (int(h[0:2],16),int(h[2:4],16),int(h[4:6],16))
+def shade(c, amt):
+    """Lighten (amt>0) or darken (amt<0) an rgb tuple toward white/black, in %."""
+    f=lambda v: max(0,min(255,round(v+(amt/100)*((255-v) if amt>0 else v))))
+    return (f(c[0]),f(c[1]),f(c[2]))
+
+# fixed semantic colours shared by every agent (danger/success/etc are universal)
+SEM = {"red":_rgb("ff1212"), "green":_rgb("36c76a"), "amber":_rgb("f2b01e"),
+       "blue":_rgb("3a9bff"), "grey":_rgb("4a4a58"), "ink":_rgb("14141e"),
+       "white":_rgb("f5f5fa")}
+
+def palette(accent_hex):
+    a=_rgb(accent_hex)
+    p=dict(SEM)
+    p.update(accent=a, acc_dim=shade(a,-52), acc_deep=shade(a,-66),
+             acc_hot=shade(a,34), acc_spark=shade(a,72),
+             grey_d=shade(SEM["grey"],-42), green_d=shade(SEM["green"],-70),
+             amber_d=shade(SEM["amber"],-78), red_deep=shade(SEM["red"],-66))
+    return p
+
+# ------------------------------------------------------------------ motif ----
+class Motif:
+    """A 17x17 mark + the cell roles the animation vocabulary needs."""
+    def __init__(self, grid, core=None, dots=None, sparks=None):
+        self.grid=grid; self.N=len(grid); self.cx=self.cy=(self.N-1)/2
+        self.filled=[(x,y) for y in range(self.N) for x in range(self.N) if grid[y][x]]
+        self.core=core if core is not None else []
+        coreset=set(self.core)
+        ringc=[(x,y) for (x,y) in self.filled if (x,y) not in coreset]
+        # order ring cells by angle from top, clockwise — the animatable path
+        self.ring=sorted(ringc, key=lambda p:(math.atan2(p[1]-self.cy,p[0]-self.cx)+math.pi/2)%(2*math.pi))
+        self.dots=dots if dots is not None else []
+        self.sparks=sparks if sparks is not None else []
+    def ang(self,x,y): return (math.atan2(y-self.cy,x-self.cx))%(2*math.pi)
+
+    @staticmethod
+    def oneman():
+        g=[[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0],
+        [0,0,0,0,1,1,0,1,1,1,0,1,1,0,0,0,0],[0,0,0,1,1,1,0,1,1,1,0,1,1,1,0,0,0],
+        [0,0,1,1,1,1,0,1,1,1,0,1,1,1,1,0,0],[0,1,1,1,1,0,0,1,1,1,0,0,1,1,1,1,0],
+        [0,1,1,1,0,0,0,1,1,1,0,0,0,1,1,1,0],[0,1,1,1,0,0,0,1,1,1,0,0,0,1,1,1,0],
+        [0,1,1,1,0,0,0,1,1,1,0,0,0,1,1,1,0],[0,1,1,1,0,0,0,0,0,0,0,0,0,1,1,1,0],
+        [0,1,1,1,0,0,0,0,0,0,0,0,0,1,1,1,0],[0,1,1,1,1,0,0,0,0,0,0,0,1,1,1,1,0],
+        [0,0,1,1,1,1,0,0,0,0,0,1,1,1,1,0,0],[0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0],
+        [0,0,0,0,1,1,1,1,1,1,1,1,1,0,0,0,0],[0,0,0,0,0,1,1,1,1,1,1,1,0,0,0,0,0],
+        [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]
+        core=[(x,y) for y in range(17) for x in range(17) if g[y][x] and x in (7,8,9) and y<=9]
+        dots=[(6,10),(8,10),(10,10)]
+        sparks_lv=[[],[(8,0),(1,5),(15,5),(0,8),(16,8)],
+                   [(8,0),(7,0),(9,0),(1,4),(15,4),(0,8),(16,8),(1,12),(15,12)]]
+        m=Motif(g, core=core, dots=dots, sparks=sparks_lv); return m
+
+# --------------------------------------------------------------- badges ------
+GLYPH = {
+ "dot":["00000","00000","00100","00000","00000"],"check":["00000","00001","00010","10100","01000"],
+ "x":["10001","01010","00100","01010","10001"],"pause":["01010","01010","01010","01010","01010"],
+ "slash":["00001","00010","00100","01000","10000"],"clock":["01110","10101","10111","10001","01110"],
+ "lock":["01110","01010","11111","11011","11111"],"shield":["11111","11111","01110","01110","00100"],
+ "up":["00100","01110","11111","00100","00100"],"gear":["01010","11111","01110","11111","01010"],
+}
+def put_badge(px, name, bg, fg, N):
+    for yy in range(0,6):
+        for xx in range(11, min(17,N)): px[(xx,yy)]=None
+    g=GLYPH[name]
+    for r in range(5):
+        for c in range(5): px[(12+c,r)] = fg if g[r][c]=="1" else bg
+
+# ------------------------------------------------- animation primitives ------
+# Each returns {(x,y): rgb|None} for frame t of nf. `col` is the state's base.
+def _fillall(m,col): return {p:col for p in m.filled}
+def tri(t,nf): x=(2*t/nf); return x if x<=1 else 2-x        # 0..1..0 triangle
+
+def mo_breathe(m,col,t,nf,P,amt=16):
+    return _fillall(m, shade(col, amt*tri(t,nf)))
+def mo_breathe_slow(m,col,t,nf,P): return mo_breathe(m,col,t,nf,P,amt=10)
+def mo_pulse(m,col,t,nf,P):
+    k=tri(t,nf); return _fillall(m, tuple(round(col[i]+(P["acc_hot"][i] if col==P["accent"] else shade(col,55)[i]-col[i])*0 + (shade(col,42)[i]-col[i])*k) for i in range(3)))
+def mo_blink(m,col,t,nf,P): return _fillall(m, col if t%2==0 else shade(col,-60))
+def mo_arc(m,col,t,nf,P,win=80,hot=None):
+    px=_fillall(m,P["acc_dim"]); hot=hot or P["acc_hot"]; ang0=(t/nf)*2*math.pi; w=math.radians(win)
+    for (x,y) in m.ring:
+        a=m.ang(x,y); da=min((a-ang0)%(2*math.pi),(ang0-a)%(2*math.pi))
+        if da<=w/2: px[(x,y)]=hot
+    for p in m.core: px[p]=col
+    return px
+def mo_scan(m,col,t,nf,P): return mo_arc(m,col,t,nf,P,win=34,hot=P["acc_spark"])
+def mo_spin(m,col,t,nf,P): return mo_arc(m,col,t,nf,P,win=54)
+def mo_dualarc(m,col,t,nf,P):
+    px=_fillall(m,P["acc_dim"]); ang0=(t/nf)*2*math.pi; w=math.radians(70)
+    for (x,y) in m.ring:
+        a=m.ang(x,y)
+        for b in (ang0,ang0+math.pi):
+            if min((a-b)%(2*math.pi),(b-a)%(2*math.pi))<=w/2: px[(x,y)]=P["acc_hot"]
+    for p in m.core: px[p]=col
+    return px
+def mo_fill(m,col,t,nf,P,core_from=0.0):
+    px=_fillall(m,P["acc_dim"]); prog=(t+1)/nf
+    for (x,y) in m.ring:
+        a=(m.ang(x,y)+math.pi/2)%(2*math.pi)
+        if a/(2*math.pi)<=prog: px[(x,y)]=col
+    for p in m.core:
+        if prog>=core_from: px[p]=col
+    return px
+def mo_boot(m,col,t,nf,P): return mo_fill(m,col,t,nf,P,core_from=0.7)
+def mo_dots(m,col,t,nf,P):
+    px=_fillall(m,col); lit=t%max(1,len(m.dots))
+    for i,p in enumerate(m.dots): px[p]=P["acc_spark"] if i==lit else P["acc_deep"]
+    return px
+def mo_sparkout(m,col,t,nf,P):
+    px=_fillall(m,col); step=[0,1,2,1][t%4]
+    for p in m.sparks[step]: px[p]=P["acc_spark"] if step==2 else P["acc_hot"]
+    return px
+def mo_sparkin(m,col,t,nf,P):
+    px=_fillall(m,col); step=[2,1,0,1][t%4]
+    for p in m.sparks[step]: px[p]=P["acc_spark"]
+    return px
+def mo_celebrate(m,col,t,nf,P):
+    cyc=[P["green"],P["amber"],P["accent"],P["acc_spark"]]
+    px=_fillall(m,cyc[t%len(cyc)]); step=[0,1,2,2][t%4]
+    for p in m.sparks[step]: px[p]=P["acc_spark"] if t%2 else P["white"]
+    return px
+
+MOTION = {"breathe":mo_breathe,"breathe_slow":mo_breathe_slow,"pulse":mo_pulse,"blink":mo_blink,
+ "arc":mo_arc,"scan":mo_scan,"spin":mo_spin,"dualarc":mo_dualarc,"fill":mo_fill,"boot":mo_boot,
+ "dots":mo_dots,"sparkout":mo_sparkout,"sparkin":mo_sparkin,"celebrate":mo_celebrate}
+
+# ------------------------------------------------- state catalog (32) --------
+# state: (group, colour-role, motion, badge|None, fps)
+A="accent"
+CATALOG = {
+ # power / lifecycle
+ "off":("power","grey","breathe_slow",None,6),      "booting":("power",A,"boot",None,8),
+ "idle":("power","acc_dim","breathe",None,6),        "active":("power",A,"breathe",None,7),
+ "paused":("power","amber","breathe",("pause","amber_d","white"),6),
+ "offline":("power","grey","breathe_slow",("slash","grey_d","white"),4),
+ # work / process
+ "thinking":("work",A,"arc",None,11),               "loading":("work",A,"fill",None,9),
+ "syncing":("work",A,"dualarc",None,10),            "writing":("work",A,"dots",None,5),
+ "streaming":("work",A,"pulse",None,6),             "queued":("work","amber","breathe",("clock","amber_d","white"),6),
+ "scanning":("work",A,"scan",None,16),              "deploying":("work",A,"fill",("up","ink","white"),9),
+ # communication
+ "speaking":("comms",A,"sparkout",None,5),          "listening":("comms","blue","sparkin",None,5),
+ "notification":("comms",A,"pulse",("dot","white","accent"),6),
+ "mention":("comms","blue","pulse",("dot","white","blue"),6),
+ "recording":("comms","red","pulse",("dot","white","red"),7),
+ # outcomes
+ "success":("outcome","green","breathe",None,7),    "warning":("outcome","amber","pulse",None,6),
+ "critical":("outcome","red","blink",None,2),       "blocked":("outcome","red","blink",("lock","ink","white"),2),
+ "error":("outcome","red","blink",("x","ink","white"),2),
+ "retrying":("outcome",A,"spin",None,12),
+ # governance / domain
+ "awaiting":("gov","amber","breathe",("clock","amber_d","white"),5),
+ "approved":("gov","green","breathe",("check","white","green"),7),
+ "rejected":("gov","red","breathe",("x","ink","white"),6),
+ "secure":("gov","green","breathe",("shield","green_d","white"),7),
+ "vulnerable":("gov","red","pulse",("shield","ink","white"),6),
+ "maintenance":("gov","grey","breathe",("gear","grey_d","white"),5),
+ "celebrating":("gov","green","celebrate",None,7),
+}
+GROUPS=["power","work","comms","outcome","gov"]
+
+def _color(role,P): return P[role] if role in P else P.get(role, P["accent"])
+
+def frames_for(m,state,P):
+    grp,role,motion,badge,fps=CATALOG[state]
+    col=_color(role,P); fn=MOTION[motion]
+    nf={"breathe":10,"breathe_slow":10,"pulse":8,"blink":2,"arc":12,"scan":12,"spin":10,
+        "dualarc":12,"fill":12,"boot":10,"dots":max(2,len(m.dots)*2),"sparkout":4,"sparkin":4,"celebrate":8}[motion]
+    out=[]
+    for t in range(nf):
+        px=fn(m,col,t,nf,P)
+        if badge:
+            nm,bg,fg=badge
+            put_badge(px, nm, P[bg], P[fg], m.N)
+        out.append(px)
+    return out, fps
+
+# ------------------------------------------------------------- renderers -----
+def render(px,N,scale):
+    img=Image.new("RGBA",(N*scale,N*scale),(0,0,0,0)); d=ImageDraw.Draw(img)
+    for (x,y),c in px.items():
+        if c is not None: d.rectangle([x*scale,y*scale,(x+1)*scale-1,(y+1)*scale-1],fill=c+(255,))
+    return img
+def svg_of(px,N):
+    from collections import defaultdict
+    by=defaultdict(list)
+    for (x,y),c in px.items():
+        if c is not None: by[c].append((x,y))
+    parts=[]
+    for c,cells in by.items():
+        rs="".join(f'<rect x="{x}" y="{y}" width="1" height="1"/>' for x,y in sorted(cells))
+        parts.append(f'<g fill="#%02x%02x%02x">{rs}</g>'%c)
+    return (f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {N} {N}" '
+            f'shape-rendering="crispEdges" role="img">{"".join(parts)}</svg>\n')
+
+def generate(m:Motif, accent="#ff1212", out="oneman", title="ONEMAN", scale=9):
+    P=palette(accent); base=os.path.join(OUT_BASE, out); os.makedirs(base, exist_ok=True)
+    meta={"title":title,"accent":accent,"N":m.N,"scale":scale,"groups":GROUPS,"states":{}}
+    for s in CATALOG:
+        frames,fps=frames_for(m,s,P)
+        imgs=[render(px,m.N,scale) for px in frames]
+        w=sum(i.width for i in imgs); strip=Image.new("RGBA",(w,imgs[0].height),(0,0,0,0)); x=0
+        for i in imgs: strip.paste(i,(x,0)); x+=i.width
+        strip.save(os.path.join(base,f"anim-{s}.png"))
+        open(os.path.join(base,f"mark-{s}.svg"),"w").write(svg_of(frames[0],m.N))  # still fallback
+        grp,role,motion,badge,_=CATALOG[s]
+        meta["states"][s]={"group":grp,"frames":len(frames),"fps":fps,"motion":motion,
+                           "badge":badge[0] if badge else None}
+    # overview sheet (representative frame 2 of each)
+    cols,rows,cell=8,4,7; tile=m.N*cell; pad=cell
+    sheet=Image.new("RGBA",(cols*tile+(cols+1)*pad,rows*tile+(rows+1)*pad),(16,16,24,255))
+    order=[s for g in GROUPS for s in CATALOG if CATALOG[s][0]==g]
+    def rep_idx(motion,n):
+        return {"blink":0,"fill":int(n*0.62),"boot":int(n*0.62),"arc":n//4,"scan":n//4,
+                "spin":n//4,"dualarc":n//4,"dots":1}.get(motion, n//2)
+    for i,s in enumerate(order):
+        fr,_=frames_for(m,s,P); im=render(fr[rep_idx(CATALOG[s][2],len(fr))],m.N,cell)
+        cx=pad+(i%cols)*(tile+pad); cy=pad+(i//cols)*(tile+pad); sheet.paste(im,(cx,cy),im)
+    sheet.save(os.path.join(base,"sprite-sheet.png"))
+    json.dump(meta, open(os.path.join(base,"states.json"),"w"), indent=1)
+    return meta
+
+if __name__=="__main__":
+    meta=generate(Motif.oneman(), accent="#ff1212", out="oneman", title="ONEMAN")
+    print(f"{title if (title:=meta['title']) else ''}: {len(meta['states'])} states, all animated")
+    print("groups:", ", ".join(GROUPS))
+    print("states:", ", ".join(meta["states"]))

package/bundled-tools/runtime/spirit_face.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""ONEMAN Core-Agent faces — the O mark IS the face.
+Thin accent rim (bigger face) -> larger, varied eyes. Mixed gender; women wear
+long hair. Distinct hair silhouette + one personality prop per agent."""
+import math
+from PIL import Image, ImageDraw
+W=H=28
+def _rgb(h):h=h.lstrip('#');return(int(h[0:2],16),int(h[2:4],16),int(h[4:6],16))
+def shade(c,a):
+    f=lambda v:max(0,min(255,round(v+(a/100)*((255-v)if a>0 else v))));return(f(c[0]),f(c[1]),f(c[2]))
+OUT=_rgb('14141e');WHT=_rgb('f7f7fb');EYE=_rgb('1b1b26')
+cx,cy=14,13;R_OUT=11.0;R_IN=8.6                      # thin rim -> big face
+SKINS={"light":_rgb('f0c49a'),"mid":_rgb('d89c70'),"tan":_rgb('c6895a'),"deep":_rgb('9c6a44')}
+def rect(px,x0,y0,x1,y1,c):
+    for y in range(max(0,y0),min(H,y1+1)):
+        for x in range(max(0,x0),min(W,x1+1)):px[(x,y)]=c
+def ytop(x):
+    dx=x-cx;return (cy-math.sqrt(R_OUT**2-dx*dx)) if abs(dx)<=R_OUT else None
+
+def draw_eyes(px,style,SK):
+    """Bigger eyes, varied. Left cols cx-5..-3, right cx+3..+5."""
+    def one(side,lash=False,shut=False,small=False,wide=False):
+        s=side
+        L=[cx+ s*3,cx+s*4,cx+s*5]
+        if shut:
+            for x in L:px[(x,cy-1)]=OUT
+            if lash:px[(cx+s*6,cy-2)]=OUT
+            return
+        for x in L:                                  # white block 3x2
+            px[(x,cy-2)]=WHT;px[(x,cy-1)]=WHT
+        pupx=cx+s*4
+        if wide:
+            px[(pupx,cy-1)]=EYE                      # small pupil, lots of white
+        elif small:
+            px[(pupx,cy-1)]=EYE
+        else:
+            px[(pupx,cy-1)]=EYE;px[(pupx,cy-2)]=EYE  # big pupil
+        px[(cx+s*3 if s<0 else cx+s*5,cy-2)]=WHT     # keep a white glint corner
+        if lash:
+            px[(cx+s*6,cy-2)]=OUT;px[(cx+s*5,cy-3)]=OUT;px[(cx+s*3,cy-2)]=OUT
+    if style=="wink":
+        one(-1);one(1,shut=True)
+    elif style=="lash":
+        one(-1,lash=True);one(1,lash=True)
+    elif style=="wide":
+        one(-1,wide=True);one(1,wide=True)
+    elif style=="small":
+        one(-1,small=True);one(1,small=True)
+    elif style=="happy":
+        for s in(-1,1): px[(cx+s*5,cy-1)]=OUT;px[(cx+s*4,cy-2)]=OUT;px[(cx+s*3,cy-1)]=OUT
+    else:  # round
+        one(-1);one(1)
+
+def hair_crown(px,HA,HAs,HAh,style):
+    def up(dx):
+        a=abs(dx)
+        return {"buzz":0,"short":1,"slick":1,"spiky":(3 if dx%2==0 else 1),
+                "longstraight":1,"longwavy":1,"ponytail":1,"longbob":1}.get(style,1)
+    def down(dx):
+        return {"buzz":1,"short":2,"slick":(3 if dx>0 else 1)}.get(style,2)
+    for x in range(cx-11,cx+12):
+        yt=ytop(x)
+        if yt is None:continue
+        base=round(yt)
+        if base>cy-2:continue
+        u=up(x-cx)
+        topy=base-u;boty=min(base+down(x-cx),cy-3)
+        for y in range(topy,boty+1):
+            if 0<=y<H:px[(x,y)]=HA
+        if 0<=topy<H:px[(x,topy)]=HAh
+        if 0<=boty<H and px.get((x,boty))==HA:px[(x,boty)]=HAs
+
+def hair_sides(px,HA,HAs,style):
+    # women's long hair: side panels of different length/shape
+    for x in range(cx-11,cx+12):
+        dx=x-cx;a=abs(dx)
+        if a<6 or a>10:continue
+        yt=ytop(x)
+        if yt is None:continue
+        top=round(yt)
+        if style=="longstraight":L=cy+7
+        elif style=="longwavy":L=cy+6+(1 if (x%2==0) else -1)
+        elif style=="longbob":L=cy+2
+        elif style=="ponytail":L=cy
+        else:L=cy-1
+        for y in range(top,min(H,L+1)):px[(x,y)]=HA
+        if L<H:px[(x,min(H-1,L))]=HAs
+    if style=="ponytail":
+        for yy in range(cy-4,cy+5):                  # tail on the right
+            for xx in range(cx+9,cx+12):
+                if abs((yy-cy))<=4-(xx-(cx+9)):px[(xx,yy)]=HA
+        px[(cx+9,cy+4)]=HAs
+        px[(cx+8,cy-5)]=HA                            # tie base
+
+def face(accent,hair,skin="mid",*,gender="m",hairstyle="short",eyes="round",
+         mouth="smile",prop=None,propcol="#caa472",hoodie=False,band=None,mask=None,specs=False):
+    AC=_rgb(accent);ACd=shade(AC,-30);SK=SKINS[skin];SKs=shade(SK,-20)
+    HA=_rgb(hair);HAs=shade(HA,-28);HAh=shade(HA,22)
+    px={}
+    for y in range(H):
+        for x in range(W):
+            d=math.hypot(x-cx,y-cy)
+            if d<=R_OUT:px[(x,y)]=(AC if d<R_OUT-0.9 else ACd) if d>=R_IN else SK
+    for y in range(0,cy-3):
+        for x in range(cx-2,cx+3):
+            if px.get((x,y)) in(AC,ACd):del px[(x,y)]
+    for x in range(cx-5,cx+6):
+        if px.get((x,cy+5))==SK:px[(x,cy+5)]=SKs
+    if gender=="f":hair_sides(px,HA,HAs,hairstyle)    # draw long hair behind/around first
+    if hairstyle!="bald":hair_crown(px,HA,HAs,HAh,hairstyle)
+    draw_eyes(px,eyes,SK)
+    px[(cx,cy+2)]=SKs                                 # nose
+    if mouth=="smile":
+        px[(cx-2,cy+4)]=OUT;px[(cx-1,cy+5)]=OUT;px[(cx,cy+5)]=OUT;px[(cx+1,cy+5)]=OUT;px[(cx+2,cy+4)]=OUT
+    elif mouth=="flat":rect(px,cx-2,cy+4,cx+1,cy+4,OUT)
+    elif mouth=="smirk":
+        px[(cx-1,cy+5)]=OUT;px[(cx,cy+5)]=OUT;px[(cx+1,cy+4)]=OUT;px[(cx+2,cy+3)]=OUT
+    elif mouth=="open":rect(px,cx-2,cy+4,cx+1,cy+5,OUT);px[(cx-1,cy+5)]=_rgb('7a1a12')
+    elif mouth=="lips":rect(px,cx-2,cy+4,cx+1,cy+4,_rgb('c0392b'))   # lipstick
+    # props
+    if prop=="cigar":
+        PC=_rgb(propcol);rect(px,cx+2,cy+4,cx+8,cy+4,PC);px[(cx+2,cy+4)]=shade(PC,-25)
+        px[(cx+8,cy+4)]=_rgb('ff4422');px[(cx+9,cy+4)]=_rgb('ffb08a')
+        px[(cx+9,cy+2)]=_rgb('8a8a9a');px[(cx+10,cy+1)]=_rgb('6a6a7a')
+    elif prop=="shades":
+        rect(px,cx-6,cy-2,cx-2,cy,OUT);rect(px,cx+2,cy-2,cx+6,cy,OUT)
+        rect(px,cx-1,cy-2,cx+1,cy-2,OUT);px[(cx-7,cy-2)]=OUT;px[(cx+7,cy-2)]=OUT
+        px[(cx-5,cy-1)]=_rgb('3a3a4a');px[(cx+3,cy-1)]=_rgb('3a3a4a')
+    elif prop=="glasses":
+        for x in range(cx-6,cx-1):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx-6,cy-1)]=OUT;px[(cx-2,cy-1)]=OUT
+        for x in range(cx+2,cx+7):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx+1,cy-1)]=OUT;px[(cx+6,cy-1)]=OUT;px[(cx,cy-1)]=OUT
+    elif prop=="monocle":
+        for x in range(cx+2,cx+7):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx+1,cy-1)]=OUT;px[(cx+6,cy-1)]=OUT
+        px[(cx+4,cy+1)]=_rgb('d4af37');px[(cx+4,cy+2)]=_rgb('d4af37')
+    elif prop=="pen":
+        PC=_rgb(propcol)
+        for i in range(5):
+            x=cx+8+i;y=cy-2-i
+            if 0<=x<W and 0<=y<H:px[(x,y)]=PC
+        px[(cx+8,cy-2)]=_rgb('2a2a34');px[(cx+12,cy-6)]=shade(PC,30)
+    elif prop=="headset":
+        rect(px,cx-12,cy-6,cx-12,cy+1,OUT);px[(cx-12,cy+2)]=OUT
+        rect(px,cx-13,cy+1,cx-12,cy+3,EYE);rect(px,cx-12,cy+3,cx-6,cy+4,OUT);px[(cx-6,cy+4)]=_rgb('ff4422')
+    elif prop=="earbuds":
+        px[(cx-9,cy)]=WHT;px[(cx-9,cy+1)]=WHT;px[(cx+9,cy)]=WHT;px[(cx+9,cy+1)]=WHT
+    elif prop=="bandana":
+        BC=_rgb(propcol)
+        for x in range(cx-11,cx+12):
+            yt=ytop(x)
+            if yt is None:continue
+            base=round(yt)
+            for y in range(base-1,base+3):
+                if 0<=y<H and y<=cy-3 and px.get((x,y)) not in(None,SK,SKs):px[(x,y)]=BC
+        px[(cx-10,cy-2)]=BC;px[(cx-11,cy-1)]=BC;px[(cx-11,cy)]=shade(BC,-22)
+        for x in range(cx-6,cx+7,3):px[(x,cy-5)]=shade(BC,-22)
+    # ---- combinable wearables (Founder) ----
+    if hoodie:
+        HC=_rgb('161b22')
+        for y in range(cy-2,H):
+            for x in range(W):
+                d=math.hypot(x-cx,y-cy)
+                if R_OUT<d<=R_OUT+2.4 and px.get((x,y)) is None: px[(x,y)]=HC
+    if band:
+        BC=_rgb(band); BCd=shade(BC,-24)
+        for y in range(0,cy-6):                              # hair crown above the (raised) band
+            for x in range(cx-9,cx+10):
+                if px.get((x,y))==SK: px[(x,y)]=HA
+        for y in (cy-6,cy-5,cy-4):                           # headband, raised a touch
+            for x in range(cx-10,cx+11):
+                yt=ytop(x)
+                if yt is None: continue
+                if y>=round(yt)-1 and px.get((x,y)) is not None: px[(x,y)]=BC
+        for strand in (0,1):                                 # two tails, both streaming up-right (wind-blown)
+            for k in range(6):
+                xx=cx+8+k; yy=(cy-2-strand*2)-(k*2)//3
+                if 0<=xx<W and 0<=yy<H: px[(xx,yy)]=BC if k<3 else BCd
+    if mask:
+        MC=_rgb(mask);MCs=shade(MC,34);GL=_rgb('39d353')
+        for y in range(cy+1,cy+10):                         # dark mask over nose+mouth+chin (follows the face)
+            for x in range(cx-8,cx+9):
+                if px.get((x,y)) in(SK,SKs): px[(x,y)]=MC
+        for x in range(cx-5,cx+6):
+            if px.get((x,cy+1))==MC: px[(x,cy+1)]=MCs        # ridge over the nose
+        for y in range(cy+2,cy+8):
+            if px.get((cx,y))==MC: px[(cx,y)]=MCs            # centre seam
+        for k in range(3): px[(cx+3,cy+4+k)]=GL;px[(cx+4,cy+4+k)]=GL   # green vent stripes
+    if specs:
+        LENS=_rgb('1f8a3a')
+        rect(px,cx-6,cy-2,cx-2,cy,OUT); rect(px,cx-5,cy-2,cx-3,cy-1,LENS); px[(cx-4,cy-1)]=_rgb('0c1a10')
+        rect(px,cx+2,cy-2,cx+6,cy,OUT); rect(px,cx+3,cy-2,cx+5,cy-1,LENS); px[(cx+4,cy-1)]=_rgb('0c1a10')
+        px[(cx-1,cy-1)]=OUT;px[(cx,cy-1)]=OUT;px[(cx+1,cy-1)]=OUT      # bridge
+    return px
+
+FOUNDER=("FOUNDER","#2fbf52","m",dict(hair="#141419",skin="light",hairstyle="short",eyes="happy",mouth="flat",band="#e23b3b",mask="#12201a",hoodie=True,specs=True))
+
+def render(px,scale,bg=None):
+    img=Image.new("RGBA",(W*scale,H*scale),(bg or(0,0,0,0)));d=ImageDraw.Draw(img)
+    for (x,y),c in px.items():
+        if c is not None:d.rectangle([x*scale,y*scale,(x+1)*scale-1,(y+1)*scale-1],fill=c+(255,))
+    return img
+
+CAST=[
+ ("CEO","#f59e0b","m",dict(hair="#2a2018",skin="mid",  hairstyle="slick",eyes="round",mouth="smirk",prop="cigar")),
+ ("CPO","#8b5cf6","f",dict(hair="#3a2418",skin="tan",  hairstyle="longwavy",eyes="lash",mouth="smile",prop="pen",propcol="#f2c75a")),
+ ("CMO","#ec4899","f",dict(hair="#4a2a18",skin="light",hairstyle="longstraight",eyes="lash",mouth="lips",prop="shades")),
+ ("CRO","#84cc16","m",dict(hair="#1c1c22",skin="mid",  hairstyle="spiky",eyes="wide",mouth="open",prop="headset")),
+ ("CTO","#3b82f6","m",dict(hair="#1c1c22",skin="tan",  hairstyle="buzz",eyes="round",mouth="flat",prop="glasses")),
+ ("COO","#06b6d4","f",dict(hair="#15151c",skin="deep", hairstyle="ponytail",eyes="lash",mouth="smile",prop="earbuds")),
+ ("CFO","#2dd4bf","f",dict(hair="#6a4a2a",skin="light",hairstyle="longbob",eyes="lash",mouth="flat",prop="monocle")),
+ ("CSO","#6366f1","m",dict(hair="#1c1c22",skin="mid",  hairstyle="short",eyes="wide",mouth="flat",prop="bandana",propcol="#ef4444")),
+]
+if __name__=="__main__":
+    scale=10;gap=14;lblh=22;cols=4;rows=2;cw=W*scale;ch=H*scale
+    sheet=Image.new("RGBA",(cols*cw+(cols+1)*gap, rows*(ch+lblh)+gap),(13,13,20,255));d=ImageDraw.Draw(sheet)
+    for i,(nm,acc,g,p) in enumerate(CAST):
+        im=render(face(acc,gender=g,**p),scale)
+        x=gap+(i%cols)*(cw+gap);y=lblh+(i//cols)*(ch+lblh)
+        sheet.paste(im,(x,y),im);d.text((x+4,y-16),f"{nm} {'F' if g=='f' else 'M'} {p['hairstyle']}/{p['prop']}",fill=(220,220,235))
+    sheet.save("/tmp/face_preview.png");print("wrote",sheet.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/agent-goal-design.md

@@ -0,0 +1,92 @@
+# Goal-led AI agent design
+
+A reusable method for defining the agents in a multi-agent product so a single
+human can run a company by stating intent, not by operating tools. Distilled
+from the ONEMAN.APP cofounder build; pairs with the `maggie-spirit` skill (give
+each designed agent a spirit/avatar) and `maggie-assistant-tools` (expose an
+agent's capabilities safely).
+
+## Principle
+
+The human sets a **goal**; the agents turn it into work and keep the human in
+the loop only for judgement and approval. Each agent owns one lane, declares the
+**capability classes** it may use, and runs under a **risk ceiling** with
+explicit approval gates. Nothing that is risky, public, or spends money happens
+without a human yes.
+
+## Define each agent with a role contract
+
+One `role.yaml` per agent. Recommended fields:
+
+```yaml
+role: CTO                     # the lane
+name: AI CTO                  # display name
+persona: Turing               # inspiration, not impersonation
+spirit: Engineering           # one-word identity (drives the spirit accent/motif)
+summary: >                    # what it owns, in one or two sentences
+  Technical design, build, integrate, test and deploy. Production deployment is
+  gated behind human approval.
+responsibilities: [design, build, integrate, test, deploy, observe]
+constraints: [no prod deploy without approval, no secrets in source]
+allowed_capability_classes: [app.scaffold, app.build, app.test, code.review,
+  deploy.release, integration.connect, ops.observe, job.execute]
+default_risk_ceiling: L1      # L0 read -> L3 irreversible/public/paid
+business_system: Execution    # which paired system (e.g. with COO)
+raci: { new_service_app: "A", security_verdict: I }
+interfaces: { mcp: planned, cli: planned, api: planned }
+```
+
+- **Capability classes**, not freeform skills, are the unit of authority. They
+  are stable `area.verb` identifiers (`content.publish`, `revenue.close`,
+  `security.scan`) that a UI can list and a gate can check. These are the
+  "skills" a product surfaces per agent.
+- **One CEO orchestrates.** The CEO owns `goal.decompose`, `mission.manage`,
+  `plan.compose`, `priority.rank`, `outcome.accept`: it turns intent into
+  missions with acceptance criteria, delegates each to the right agent, and
+  signs off - it never bypasses security or budget approval.
+- **Security holds a non-overridable veto.** A high-risk security verdict cannot
+  be overruled by another agent.
+- **Finance is explain-only.** Financial facts come from deterministic data
+  (billing/usage ledger, Stripe); the CFO reconciles and advises, it is not the
+  source of truth.
+
+## Risk ceilings and approval gates
+
+| Level | Meaning | Gate |
+|---|---|---|
+| L0 | read-only | none |
+| L1 | internal writes (drafts, plans, workflows) | logged |
+| L2 | customer-facing or public (publish, close a deal) | human approval |
+| L3 | irreversible / paid / production (deploy, transfer) | human approval + audit |
+
+Every agent declares a `default_risk_ceiling`; an action above it stops for an
+explicit human yes. Log every action; make L2/L3 produce an approval card.
+
+## The goal loop
+
+1. The human states what the business should do.
+2. The CEO writes missions with acceptance criteria.
+3. Each mission is delegated to the agent whose lane and capability classes fit.
+4. Agents work their lane; risky/public/paid steps wait for approval.
+5. The CEO reviews outcomes against the acceptance criteria and signs off, or
+   sends the mission back.
+6. The human stays the only human in the loop - approve, steer, ship.
+
+## Surfacing agents to users
+
+Each agent reads cleanly as a profile: persona name, spirit, its capability
+classes (its "skills"), and the service apps it manages. Give it a spirit/avatar
+with `maggie-spirit` (shared 32-state motion vocabulary, per-agent accent) so
+status (idle, working, deploying, success, blocked, secure) reads the same
+across the whole team. Mark an agent "shipped" only when its product is actually
+live.
+
+## Checklist
+
+- [ ] One lane per agent; no two agents own the same decision.
+- [ ] Capability classes are `area.verb`, stable, and enumerable.
+- [ ] A single orchestrator (CEO) owns decomposition and sign-off.
+- [ ] Security veto and finance-is-explain-only are encoded, not assumed.
+- [ ] Every agent has a risk ceiling; L2/L3 actions gate on human approval.
+- [ ] Persona is inspiration, not impersonation of a real person.
+- [ ] Each agent has a spirit/avatar from the shared 32-state base set.