docs: add Pearcord brand theme guide and module index

Document the pearcord theme palette, asset sync paths, and pearcord-branding module role.

Co-authored-by: Cursor <[email protected]>

BRANDING_THEME.md

@@ -0,0 +1,35 @@
+# Pearcord brand theme
+
+Optional UI theme **`pearcord`** (`html[data-theme="pearcord"]`) applies official brand colors from the [`pearcord-branding`](../modules/pearcord-branding) module. Default theme remains **`dark`**.
+
+## Palette
+
+| Token | Hex | Role |
+|-------|-----|------|
+| Dark navy | `#0F172A` | Deepest surfaces (`--pc-bg-tertiary`) |
+| Navy steps | `#111827`, `#1e293b`, `#334155` | Panels, hovers, borders |
+| Primary emerald | `#059669` | Primary accent (`--pc-blurple`, buttons, active rail) |
+| Accent cyan | `#14B8A6` | Links and success tint (`--pc-link`, `--pc-green`) |
+| Text | `#f1f5f9` / `#94a3b8` | Body and muted copy |
+
+Canonical JS export: `PEARCORD_THEME_TOKENS` in `pearcord-branding/index.js` (keep in sync with `apps/pearcord/ui/styles/pearcord.css`).
+
+## Asset map
+
+Synced into the app via `npm run sync:branding` (`apps/pearcord/scripts/sync-branding-assets.cjs`):
+
+| UI surface | File |
+|------------|------|
+| DM home rail button | `ui/assets/branding/pearcord-dm-icon.png` (from `pearcord-app-icon-transparent.png`) |
+| Onboarding splash | `ui/assets/branding/pearcord-onboarding-icon.png` |
+| Favicons | `ui/assets/branding/favicon/favicon-*.png` |
+
+Full brand kit (logos, PDF guidelines): `pearcord-branding` repo / Desktop package.
+
+## User settings
+
+**Appearance → Theme → Pearcord (brand)**. Persisted locally and via P2P `USER_PREFS_UPDATE` (`pearcord-settings`).
+
+## Guidelines PDF
+
+See `pearcord-branding/guidelines/Pearcord-Brand-Guidelines.pdf` for logo clear-space and usage rules before shipping marketing surfaces.

MODULES.md

@@ -50,7 +50,7 @@ All **`pearcord-*`** packages under `modules/`. Each has its own Gitea repo and
 | `pearcord-log` | `modules/pearcord-log` | shipped | [LOGGING.md](./LOGGING.md) | `pearcord-log/README.md` |
 | `pearcord-agentctl` | `modules/pearcord-agentctl` | shipped | [AGENTCTL.md](./AGENTCTL.md) | `pearcord-agentctl/README.md` |
 | `pearcord-lottie` | `modules/pearcord-lottie` | shipped | [LOTTIE_STICKERS.md](./LOTTIE_STICKERS.md) | `pearcord-lottie/README.md` |
-| `pearcord-branding` | `modules/pearcord-branding` | shipped | — | `pearcord-branding/README.md` |
+| `pearcord-branding` | `modules/pearcord-branding` | shipped | [BRANDING_THEME.md](./BRANDING_THEME.md) | `pearcord-branding/README.md` |
 | `pearcord-boosts` | `modules/pearcord-boosts` | shipped | [GUILD_BOOSTS.md](./GUILD_BOOSTS.md) | `pearcord-boosts/README.md` |
 | `pearcord-announcements` | `modules/pearcord-announcements` | shipped | [ANNOUNCEMENT_FOLLOW.md](./ANNOUNCEMENT_FOLLOW.md) | `pearcord-announcements/README.md` |
 | `pearcord-announcement-hub` | `modules/pearcord-announcement-hub` | shipped | [ANNOUNCEMENT_HUB.md](./ANNOUNCEMENT_HUB.md) | `pearcord-announcement-hub/README.md` |
@@ -111,7 +111,7 @@ Packages **not** listed as direct platform dependencies but used by the app or o
 | `pearcord-shared` | Every module |
 | `pearcord-db` | identity, guild, message, invite |
 | `pearcord-bot-runner` | `apps/pearcord/worker`, CLI |
-| `pearcord-branding` | Static logos/favicons; optional `require('pearcord-branding')` in app or docs |
+| `pearcord-branding` | Logos, favicons, `PEARCORD_THEME_TOKENS`, `sync:branding` → UI assets; see [BRANDING_THEME.md](./BRANDING_THEME.md) |
 | `pearcord-integration-worker` | Server settings / worker templates |
 | `pearcord-digest-relay-plugin` | Platform automation + `GUILD_SYNC` slice |
 | `pearcord-sync` | Not wired |