Brand assets

brand.config.json owns the mapping from public export paths to local asset files. brand.lock.json pins their version, source revision, archive SHA-256, download URL, and individual checksums. Normal builds verify committed bytes without fetching private artwork or requiring private credentials.

just brand-check
just brand-sync /path/to/phux-brand.zip SHA256
just brand-restore

The canonical installer is itself a release export, delivered to scripts/brand.py through the same pin. Change artwork or static geometry in phux-brand, inspect its preview, and publish a new approved version. Consumer CI rejects edits that drift from the pin. Product code continues to own behavior, animation, and platform resource packaging.

Choosing branding in the apps

Open Settings → Appearance → Brand profile to choose Flat Fox, Silver Fox or Classic Prompt. All choices ship offline. Desktop remembers one choice across windows and workspaces; mobile saves it on the device. Changing a host or account does not reset it. The picker reports icon or preference-save failures.

macOS changes the running Dock icon and restores the choice on launch; Finder keeps the signed release icon. Linux updates a user-local launcher entry while preserving its command; refresh timing belongs to the launcher. iOS uses alternate app icons and Android uses launcher aliases alongside the selected in-app marks.

Selecting the release default

The private library’s profiles.json.selected sets the shared release default for Flat Fox, Silver Fox or Classic Prompt. Run just profile <id> there to render the chosen profile for every platform, then review and publish its kit. Flat Fox is the default. identity/profile.json travels with the assets and is installed as clients/desktop/packaging/brand-profile.json here.

Desktop packaging uses desktopBrand() for the selected profile and its PNG/SVG paths. Native apps additionally bundle every approved choice. Mobile drawing and launch silhouettes use their native brand interface over the selected geometry and finish. Desktop’s process-wide branding interface owns its saved choice, preview and platform icon. Clients keep stable asset paths and do not branch on profile names.

Publishing and updates

phux-brand checks the catalog’s explicit public approval, generated mobile exports, and archive integrity before creating an immutable GitHub release. Drafts, private originals, and unreviewed media never enter its export bundle. The bundle includes a preview, usage guidance, a manifest, and approved assets.

The hourly brand-update workflow in this repository reads those private releases through the existing release bot. A read-only token is scoped to phux-brand; a second token may open update PRs in phux, phux-mobile, and website. Neither key nor private originals are copied into consumer repos. The updater verifies the GitHub asset digest, every file checksum, and the tagged source revision before proposing changes. All three consumer gates run without private credentials, including builds from public forks.

Run an update immediately with:

gh workflow run brand-update.yml --repo no-phux/phux

Each consumer receives an ordinary PR and remains subject to its existing merge/release gates. The website update also retains the approved release archive and publishes its manifest/checksum through the existing deployment. Updating branding does not automatically release a desktop or mobile app.

Rollback and repair

Install an earlier bundle with its original SHA-256 to roll back locally. For coordinated rollback PRs, dispatch brand-update with an explicit version and allow_rollback=true. Scheduled updates never downgrade a pin. Old public archives remain available so older consumer versions can restore their assets. Never rewrite or replace a published brand version.

A rollback bundle must supply every export required by the checked-in mapping, and its geometry must match the platform code. When reversing a change that added exports or changed the geometry API, revert the matching consumer configuration and platform code together with the pin. Missing required exports are rejected before any files are written.

brand-restore repairs local drift using the existing public pin. A malformed bundle fails before writing files; a failed write restores previous bytes. An interrupted update is detected by brand-check and can be repeated. Locally edited obsolete assets cause an error instead of being deleted. The updater reports failures per repository and can safely be rerun after correcting access or an export mapping.

Windows applies the chosen artwork to running and newly opened window icons. Explorer and pinned shortcuts retain the release icon. The Windows CI fixture exercises all approved PNGs through the actual managed native adapter without a WSL coordinator.