add-branding

name	add-branding
description	Customize app shell branding - themes, colors, navigation, logos. Works with app/brand/ and app/config/ declarative files.
argument-hint	[what you want to change - theme, colors, logo, navigation]

Before starting: git fetch origin && gh pr list --state open && git log origin/main --oneline -3 — if another agent has an open PR touching the same files you need, wait for it to merge or branch off it instead of main.

Help the user customize the Mozaiks app shell using declarative config.

Key Files

Read these first:

• app/app.json — App identity, auth, admin emails
• app/config/shell.json — Shell chrome config
• app/config/ai.json — Startup mode, workflow entry point
• app/brand/theme_config.json — Theme tokens

For assets:

• app/brand/assets/ — Logos, icons
• app/brand/fonts/ — Custom fonts

Questions to Ask

1. Changing visuals, shell behavior, or both?
2. Should app open on chat, a page, or adapter route?
3. Should chat start in ask mode or workflow mode?
4. Changing logos, icons, or fonts?
5. Any auth changes?

What Each File Controls

File	Controls
app/app.json	App name, auth requirement, admin emails, startup landing spot
app/brand/theme_config.json	Colors, fonts, spacing, dark/light mode, shell chrome
app/config/shell.json	Compact shell shortcuts, navigation policy, chrome mode policy, plus header/footer/profile/notification/mobile overrides
app/config/ai.json	Entry workflow, startup mode

Rules

• Do NOT invent files like brand.json, ui.json, or auth.json — these don't exist
• Prefer declarative config changes over React code changes
• Keep workflow startup settings in ai.json
• Shell branding (logos, fonts, login theme) belongs in app/brand/
• app/app.json is for app identity and startup intent — not colors or shell chrome
• Prefer app/config/shell.json -> shortcuts for common shell items so the file stays small.
• Prefer route-level ui/pages/*.yaml -> navigation for page-owned navigation entries; use app/config/shell.json -> navigation.policy for app-wide placement rules.
• Prefer route-level ui/pages/*.yaml -> shell_mode for per-route header/footer/bottom-bar behavior; use app/config/shell.json -> chrome only for app-wide mode defaults.
• Use explicit header, profile, notifications, footer, or mobile objects only when labels, icons, roles, or paths need custom overrides.
• Common shortcut ids include home, apps, workspace, wallet, create, profile, messages, notifications, settings, admin, support, signout, signin, legal, terms, cookies, and privacy. Use dashboard only when the app declares a page or route with id dashboard.

Shell Shortcuts

{
  "shortcuts": {
    "header": ["home", "wallet"],
    "profile": ["profile", "wallet", "signout", "signin"],
    "mobile": ["home", "apps", "create", "profile"],
    "footer": ["legal", "terms", "cookies"],
    "footerHideOnMobile": true
  }
}

The backend expands this into the full shell config returned by /api/shell-config.

Dynamic Navigation Policy

{
  "navigation": {
    "policy": {
      "desktop": { "global": "header", "local": "sidebar", "footer": "visible" },
      "mobile": { "global": "bottomBar", "local": "sheet", "footer": "hidden" },
      "maxMobileItems": 5,
      "autoFromPages": false
    }
  }
}

Keep autoFromPages false unless you intentionally want every page route to become global navigation.

Dynamic Chrome Modes

Pages choose a shell_mode:

shell_mode: workspace

Mode meanings:

• standard: normal app page.
• workspace: dense dashboard, admin/profile/module workspace, or local nav surface.
• conversation: chat, DM, inbox thread, or support conversation.
• focused: onboarding, setup, review, approval, checkout, or transition-like screen.
• immersive: full-viewport map, canvas, media, game, or kiosk.
• public: public, legal, marketing, or unauthenticated route.

Override mode behavior in shell.json only when the app-wide default is wrong:

{
  "chrome": {
    "defaultMode": "standard",
    "modes": {
      "conversation": {
        "desktop": { "header": true, "footer": false, "bottomBar": false, "localNav": false },
        "mobile": { "header": true, "footer": false, "bottomBar": false, "localNav": false }
      }
    }
  }
}

Verification

After changes:

1. Verify JSON parses correctly
2. Check /api/theme-config returns expected values
3. Check /api/shell-config returns expected values
4. Verify any referenced assets exist under app/brand/assets/