Branding

Branding is part of the unified core.assets system. This page documents the filesystem contract and how to request branding assets via the public resolver.

Overview

• Storage: core.assets/assets/branding/ holds the canonical files with two scopes: global/ and regional/.


• Resolution: the public resolver core.assets/public/assets.php serves assets directly from the filesystem via AssetRouter.

Files & layout

Repository layout (branding subset):

core.assets/

└── assets/

    └── branding/

        ├── global/<brand>/<asset>/{v1.svg, v2.svg, stable.md}

        └── regional/<project>/<brand>/<asset>/{v1.svg, stable.md}

Each final asset folder (e.g. core.assets/assets/branding/global/universal/vector_logo/) contains versioned files (v1.svg, v2.svg) and an optional stable.md file that specifies the stable version by filename:

v1.svg

Runtime usage

Mount core.assets/public/ as the document root of your core.assets subdomain (or route requests there). The public resolver handles both query-style and path-style requests.

Path-style (recommended)

• GET /branding/global/universal/vector_logo → latest by modification time


• GET /branding/global/universal/vector_logo?version=stable → file named in stable.md


• GET /branding/global/universal/vector_logo?version=v2 → specific version


• GET /branding/regional/my-project/my-brand/my-asset

Query-string style

• GET /branding?name=global-universal-vector_logo&version=latest


• GET /branding?name=global-universal-vector_logo&version=stable

Version resolution

Request	Behavior

?version=stable	Read stable.md → serve that file. If stable.md doesn't exist → serve latest
?version=latest	Serve newest file by modification time
?version=<name>	Serve exact file match
(no param)	Serve latest file by modification time

Response headers

• ETag — SHA1 hash of the file (supports 304 Not Modified)


• Cache-Control — explicit versions: immutable (1 year); aliases: short TTL (60s)


• CORS — permissive headers for cross-origin usage

Adding or updating an asset

1. Add the version file to the appropriate folder, e.g. core.assets/assets/branding/global/universal/vector_logo/v4.svg.


2. Update the folder's stable.md if the stable version changes (just write the filename, e.g. v4.svg).


3. Deploy — the resolver picks up new files automatically from the filesystem.

Best practices

• Treat explicit version files as immutable once published.


• Use stable.md for production-safe releases and let latest (default) serve the newest file.


• Place the .htaccess from core.assets/public/ in your Apache document root to enable clean URL routing.