Overview Files Skills Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity

name: hd-avatar description: > Generate or change the user's Adom avatar (profile picture), and make Hydrogen Desktop show the new one immediately. Use when the user says "generate a new avatar for me", "change my avatar", "make me a profile picture", "update my profile photo", "set my avatar to this image", "reset my avatar", or hands you an image. The headline flow is GENERATE: research who they actually are, propose a design, author it as an SVG, render, upload, and offer to archive the vector on a wiki page so future sizes come from a perfect source. Trigger words: avatar, generate an avatar, make me an avatar, profile picture, profile photo, change my avatar, update avatar, set avatar, reset avatar, remove avatar, my picture, headshot, profile image.

hd-avatar — generate a great avatar, then make HD show it

The avatar appears in HD's title bar and heads the profile menu (the Identity Card — see the identity-card skill). The usual request is "generate a new avatar for me" with nothing else: no image file, no brief. That is not a lack of information — it's an invitation to go find out who they are and design something that actually fits.

Do not immediately ask "what would you like?" A blank prompt puts the work back on them. Research first, then come back with two or three concrete proposals and a reason for each.

1. Learn who this person is

Start inside Adom, then widen. Take what's cheap and public; stop when you have enough to design with intent.

In the Adom ecosystem (fast, authoritative, no browsing needed):

adom-cli carbon user get      # display_name, bio, company, location, website_url
adom-cli carbon user orgs     # their organizations (name, display_name, avatar_url)
adom-cli carbon user repos    # what they actually build

Then their wiki footprint — pages they own, apps/skills they've published, their hero images (those already encode a visual identity worth echoing): adom-wiki discovery, their user page.

On the wider internet (only what's public, and only if it adds something):

Their website_url from the profile — usually the highest-signal single source.
GitHub — languages, projects, existing avatar style.
LinkedIn — role, industry, how they present professionally.
A plain web search on "<display name>" <company> for talks, articles, a personal site.
Their signed-in browser via adom-desktop (nbrowser_*, the abe extension) can reach a Google profile or anything else they're already logged into — see driving-the-extension. Prefer this over pup for logged-in surfaces.

Boundaries that matter here. This is a person, not a target. Use public sources, keep it proportionate to designing a 512px picture, and tell them what you found and where when you present the concepts. Never put anything you discovered into a public artifact without asking. If they've said they don't want research, skip straight to asking for a direction.

2. Propose, don't guess silently

Come back with 2–3 concepts, each one sentence, each tied to what you learned:

Monogram — "JL" in the Adom teal, geometric and quiet. Reads at any size; matches how your wiki heroes look.

Craft mark — a minimal PCB trace forming your initial, nodding to the hardware work in your repos.

Portrait abstraction — flat-color silhouette from your GitHub photo, so you stay recognizable across surfaces.

Say which you'd pick and why. Let them redirect before you spend effort rendering.

3. Author it as an SVG (and enjoy this part)

Vector, always. SVG is the master: infinitely rescalable, tiny, diffable, and every future PNG comes from it.

Design rules that actually matter for an avatar:

Square canvas, centered composition, safe margin — it gets clipped to a circle everywhere.
Legible at 32px. This is the real constraint. Two shapes and one accent survive; fine linework and long text do not. Zoom out and check before you ship. If it fails at 32px, the fix is usually a TIGHTER CROP (below), not a simpler drawing.
High contrast, and it must hold on both dark and light chrome.
Brand teal #00b8b0 sits naturally in Adom surfaces, but a personal avatar may deliberately differ from the platform palette — this is their identity, not a UI chrome element.
No emoji, no clip art, no gradients so subtle they mud at small sizes.

Keep the SVG in their container, e.g. ~/project/avatars/<name>-v1.svg, so it's editable later.

Frame the AVATAR tight — the master and the upload are NOT the same crop

The single most common mistake: author a lovely full composition — a character with a background, a scene, a full-body mark — render it as-is, and upload it. In a 26px circle the subject is now an unreadable speck (John hit exactly this: "you need to zoom to the face for the actual rendering of the avatar, it shows in a little circle in all the UI").

So separate the two jobs:

Master SVG — keep the full composition. It's the artwork, the thing worth archiving.
Avatar export — a tight crop on the subject: the face, the monogram, the mark. It should fill roughly 70–85% of the frame, centered, with a small safe margin.

Vector makes this free — you do not need a second drawing. Export the avatar with a viewBox that frames just the subject:

<!-- master: the whole scene -->
<svg viewBox="0 0 1000 1000"> … </svg>

<!-- avatar export: same artwork, zoomed to the face at 300,220 -->
<svg viewBox="300 220 260 260"> … </svg>

Sizes it will actually be seen at — check the crop at the SMALLEST, not the largest:

Surface	Rendered size
HD title bar	~26–36px
Profile menu (Identity Card)	44px
Identity Card, large	64px
Profile page picture	~224px

It is clipped to a circle everywhere, so keep the subject centered and put nothing that matters in the corners. Before uploading, look at the PNG scaled down to 32px: if you can't tell what it is, re-crop tighter — don't just redraw.

4. Render → upload → repaint

# SVG → PNG (512x512). Use the Puppeteer-managed Chrome: the container's chromium-browser is a
# dead stub, and `chrome --headless --screenshot` hangs on real pages. Puppeteer/CDP with an
# explicit browser.close() shoots AND exits (same pipeline as adom-wiki-hero-image).
CHROME=$(ls -d /home/adom/.cache/puppeteer/chrome/linux-*/chrome-linux64/chrome | head -1)

adom-cli carbon user avatar-upload ~/project/avatars/<name>-v1.png   # 204 = success
CTRL="$(cat ~/.adom/hd-control-url)"
curl -s -X POST "$CTRL/user/refresh"      # HD repaints instantly — otherwise it looks unchanged

Verify before claiming success: adom-cli carbon user get should show a NEW avatar_url hash. Then show them the result (inject the PNG into shotlog) rather than describing it.

5. Offer to archive the vector on the wiki

Once they like it, suggest a small personal wiki page holding the SVG plus a short note on the concept. Why it's worth doing:

The SVG is the perfect-resolution master — future PNGs (any size, a favicon, a talk slide, a business card) render from it with no quality loss.
It survives container resets and moves with them.
Iterations get a history: -v1, -v2, and the reasoning behind each.

Ask first — it's their identity and their page. If they'd rather keep it local, the container copy in step 3 is enough.

Change it from a file (when they DO have one)

adom-cli carbon user avatar-upload /path/to/image.png
adom-cli carbon user avatar-delete     # back to the generated default

Why HD goes stale, and the one call that fixes it

HD caches the signed-in user at launch, so an upload succeeds while HD keeps painting the OLD picture. POST <control>/user/refresh clears exactly that. HD also self-heals on its own the next time the profile menu opens (it re-reads then) or on next launch — but the user notices the lag, so make the call.

There is no CDN cache to bust: avatar URLs are content-hashed (cdn.adom.inc/avatars/<hash>.png), so a different image is always a different URL.

The user can also do it by hand

In HD: profile menu → click the avatar (camera badge on hover), or Your profile → Upload a photo / Remove photo. Both go through the same Carbon endpoints. The UI is the fallback; the prompt above is the main event.

---
name: hd-avatar
description: >
  Generate or change the user's Adom avatar (profile picture), and make Hydrogen Desktop show
  the new one immediately. Use when the user says "generate a new avatar for me", "change my
  avatar", "make me a profile picture", "update my profile photo", "set my avatar to this
  image", "reset my avatar", or hands you an image. The headline flow is GENERATE: research who
  they actually are, propose a design, author it as an SVG, render, upload, and offer to archive
  the vector on a wiki page so future sizes come from a perfect source. Trigger words: avatar,
  generate an avatar, make me an avatar, profile picture, profile photo, change my avatar,
  update avatar, set avatar, reset avatar, remove avatar, my picture, headshot, profile image.
---

# hd-avatar — generate a great avatar, then make HD show it

The avatar appears in HD's title bar and heads the profile menu (the **Identity Card** — see the
`identity-card` skill). The usual request is **"generate a new avatar for me"** with nothing
else: no image file, no brief. That is not a lack of information — it's an invitation to go find
out who they are and design something that actually fits.

**Do not immediately ask "what would you like?"** A blank prompt puts the work back on them.
Research first, then come back with two or three concrete proposals and a reason for each.

## 1. Learn who this person is

Start inside Adom, then widen. Take what's cheap and public; stop when you have enough to design
with intent.

**In the Adom ecosystem** (fast, authoritative, no browsing needed):
```bash
adom-cli carbon user get      # display_name, bio, company, location, website_url
adom-cli carbon user orgs     # their organizations (name, display_name, avatar_url)
adom-cli carbon user repos    # what they actually build
```
Then their wiki footprint — pages they own, apps/skills they've published, their hero images
(those already encode a visual identity worth echoing): `adom-wiki` discovery, their user page.

**On the wider internet** (only what's public, and only if it adds something):
- Their `website_url` from the profile — usually the highest-signal single source.
- **GitHub** — languages, projects, existing avatar style.
- **LinkedIn** — role, industry, how they present professionally.
- A plain web search on `"<display name>" <company>` for talks, articles, a personal site.
- **Their signed-in browser via adom-desktop** (`nbrowser_*`, the abe extension) can reach a
  Google profile or anything else they're already logged into — see `driving-the-extension`.
  Prefer this over pup for logged-in surfaces.

**Boundaries that matter here.** This is a person, not a target. Use public sources, keep it
proportionate to designing a 512px picture, and **tell them what you found and where** when you
present the concepts. Never put anything you discovered into a public artifact without asking.
If they've said they don't want research, skip straight to asking for a direction.

## 2. Propose, don't guess silently

Come back with **2–3 concepts**, each one sentence, each tied to what you learned:

> - **Monogram** — "JL" in the Adom teal, geometric and quiet. Reads at any size; matches how
>   your wiki heroes look.
> - **Craft mark** — a minimal PCB trace forming your initial, nodding to the hardware work in
>   your repos.
> - **Portrait abstraction** — flat-color silhouette from your GitHub photo, so you stay
>   recognizable across surfaces.

Say which you'd pick and why. Let them redirect before you spend effort rendering.

## 3. Author it as an SVG (and enjoy this part)

**Vector, always.** SVG is the master: infinitely rescalable, tiny, diffable, and every future
PNG comes from it.

Design rules that actually matter for an avatar:
- **Square canvas, centered composition**, safe margin — it gets clipped to a circle everywhere.
- **Legible at 32px.** This is the real constraint. Two shapes and one accent survive; fine
  linework and long text do not. Zoom out and check before you ship. If it fails at 32px, the fix
  is usually a TIGHTER CROP (below), not a simpler drawing.
- **High contrast**, and it must hold on both dark and light chrome.
- Brand teal `#00b8b0` sits naturally in Adom surfaces, but a personal avatar may deliberately
  differ from the platform palette — this is *their* identity, not a UI chrome element.
- No emoji, no clip art, no gradients so subtle they mud at small sizes.

Keep the SVG in their container, e.g. `~/project/avatars/<name>-v1.svg`, so it's editable later.

### Frame the AVATAR tight — the master and the upload are NOT the same crop

The single most common mistake: author a lovely full composition — a character with a
background, a scene, a full-body mark — render it as-is, and upload it. In a 26px circle the
subject is now an unreadable speck (John hit exactly this: *"you need to zoom to the face for
the actual rendering of the avatar, it shows in a little circle in all the UI"*).

So separate the two jobs:

- **Master SVG** — keep the full composition. It's the artwork, the thing worth archiving.
- **Avatar export** — a **tight crop on the subject**: the face, the monogram, the mark. It
  should fill roughly **70–85% of the frame**, centered, with a small safe margin.

Vector makes this free — you do not need a second drawing. Export the avatar with a **viewBox
that frames just the subject**:

```xml
<!-- master: the whole scene -->
<svg viewBox="0 0 1000 1000"> … </svg>

<!-- avatar export: same artwork, zoomed to the face at 300,220 -->
<svg viewBox="300 220 260 260"> … </svg>
```

Sizes it will actually be seen at — check the crop at the SMALLEST, not the largest:

| Surface | Rendered size |
|---|---|
| HD title bar | ~26–36px |
| Profile menu (Identity Card) | 44px |
| Identity Card, large | 64px |
| Profile page picture | ~224px |

**It is clipped to a circle everywhere**, so keep the subject centered and put nothing that
matters in the corners. Before uploading, look at the PNG scaled down to 32px: if you can't tell
what it is, re-crop tighter — don't just redraw.

## 4. Render → upload → repaint

```bash
# SVG → PNG (512x512). Use the Puppeteer-managed Chrome: the container's chromium-browser is a
# dead stub, and `chrome --headless --screenshot` hangs on real pages. Puppeteer/CDP with an
# explicit browser.close() shoots AND exits (same pipeline as adom-wiki-hero-image).
CHROME=$(ls -d /home/adom/.cache/puppeteer/chrome/linux-*/chrome-linux64/chrome | head -1)

adom-cli carbon user avatar-upload ~/project/avatars/<name>-v1.png   # 204 = success
CTRL="$(cat ~/.adom/hd-control-url)"
curl -s -X POST "$CTRL/user/refresh"      # HD repaints instantly — otherwise it looks unchanged
```

**Verify before claiming success:** `adom-cli carbon user get` should show a NEW `avatar_url`
hash. Then show them the result (inject the PNG into shotlog) rather than describing it.

## 5. Offer to archive the vector on the wiki

Once they like it, suggest a small personal wiki page holding the **SVG** plus a short note on
the concept. Why it's worth doing:
- The SVG is the perfect-resolution master — future PNGs (any size, a favicon, a talk slide, a
  business card) render from it with no quality loss.
- It survives container resets and moves with them.
- Iterations get a history: `-v1`, `-v2`, and the reasoning behind each.

Ask first — it's their identity and their page. If they'd rather keep it local, the container
copy in step 3 is enough.

## Change it from a file (when they DO have one)

```bash
adom-cli carbon user avatar-upload /path/to/image.png
adom-cli carbon user avatar-delete     # back to the generated default
```

## Why HD goes stale, and the one call that fixes it

HD caches the signed-in user at launch, so an upload succeeds while HD keeps painting the OLD
picture. `POST <control>/user/refresh` clears exactly that. HD also self-heals on its own the
next time the profile menu opens (it re-reads then) or on next launch — but the user notices the
lag, so make the call.

There is **no CDN cache to bust**: avatar URLs are content-hashed
(`cdn.adom.inc/avatars/<hash>.png`), so a different image is always a different URL.

## The user can also do it by hand

In HD: profile menu → click the avatar (camera badge on hover), or **Your profile** → *Upload a
photo* / *Remove photo*. Both go through the same Carbon endpoints. The UI is the fallback; the
prompt above is the main event.

Adom Hydrogen (platform base)