Topolo Brand

What It Is

Topolo Brand is the canonical source for reusable brand identity across Topolo applications. A brand kit combines visual tokens, approved assets, voice rules, claims, qualifiers, calls to action, accessibility requirements, and legal restrictions.

Architecture

Topolo Brand separates mutable editorial drafts from immutable published snapshots. The control database also persists one Brand workspace per organization so the shared workspace switcher uses a real authorized resource. Four concern-owned D1 databases store workspace and kit control, versioned content, asset metadata, and append-only audit events. R2 stores the governed asset bytes. Consumer applications resolve published snapshots through authenticated service bindings.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

• brand.topolo.app provides the production editor and governance surface.
• brand.stg.topolo.us provides staging verification.
• brand.topolo.dev provides the isolated development surface.
• The Brand API provides kit, version, asset, binding, resolution, and validation routes.

API Reference

The API supports kit editing, version publication, governed asset registration and upload, application-resource bindings, published-version resolution, and final-content validation. Consumer applications use read-only resolution, validation, and asset-content routes. Publication returns 422 brand_version_not_publishable with structured issues when the draft has no primary logo, references a missing or wrong-kind logo/font asset, or violates its own required foreground or primary contrast. Resolution expands stored app-relative asset paths against the serving environment so consumers always receive fetchable absolute URLs.

Versioned Brand Truth

Editors work in a mutable draft. Publishing atomically retires the prior published snapshot and publishes the selected draft inside the content database. The API derives the active version from that authoritative content state rather than maintaining a cross-database pointer. Consumer applications resolve and store the exact version ID, so updating a brand never silently changes an existing Social Studio project or obscures which rules Socialize used to generate an asset.

Claims And CTAs

Claims carry an explicit lifecycle: draft, approved, restricted, or retired. They can also carry sources, required qualifiers, regions, channels, and validity windows. Social generation may use only approved claims that are valid for the requested channel.

Calls to action are managed in the same kit. Socialize can select an approved channel-compatible CTA and validate the final output against the same immutable snapshot.

Creative Assets

Logos, fonts, imagery, icons, motion, audio, and templates are stored as governed brand assets. Every asset records its media type, license context, and accessibility text where required. The Visual workbench uploads logo assets and assigns primary, reversed, and mark roles from the version's actual asset set; a draft may be incomplete, but publishing requires a valid primary logo.

Application Bindings

Topolo Brand binds one brand kit to an application-owned resource. Socialize resolves the kit for a Socialize brand; Social Studio resolves it for a Studio workspace. Consumers receive read-only published versions and cannot mutate the canonical brand definition.

Auth and Permissions

People authenticate with Topolo Auth and require Brand read or write permissions. Auth synchronizes the organization's persisted Brand workspace and the shared shell selects only an authorized workspace ID. Application consumers authenticate as allow-listed Topolo services and receive read-only access scoped to the organization and bound resource.

Data Ownership

Topolo Brand owns kit drafts, immutable versions, governed asset metadata and bytes, claims, CTAs, and consumer bindings. Socialize retains ownership of social brands and posts; Social Studio retains ownership of workspaces and compositions.

Privacy Lifecycle

Authenticated users can export every Brand record owned by the selected workspace and can erase that workspace's app-owned records and governed asset bytes through confirmed actions. A daily retention job pseudonymizes expired identity fields and removes archived asset metadata and R2 bytes after their declared horizon. These operations remain scoped to the exact organization and Brand workspace; deleting one workspace does not affect another workspace's kits or assets.

Deployments

Brand is deployed before its consumers. A usable environment requires the Brand API and web surface, control/content/assets/audit D1 migrations, R2 object storage, Auth workspace-resource synchronization, at least one published kit, and bindings for each consumer resource.

The public marketplace entry is owned by app_topolo_brand, categorized under Delivery & Operations / Brand & Marketing, and carries the same governed description, shared catalog-generated Brand icon, price, and 24-action contract in the current staging source.

Safety Boundary

Brand validation rejects unapproved or channel-restricted claims, missing required qualifiers, banned language, invalid CTAs, unknown or wrong-kind asset references, and required palette contrast failures. Warnings such as a decorative accent below the declared minimum or an unused image without alt text remain visible without blocking publication. A published kit is a governance input, not permission for a consumer application to bypass its normal authorization or publishing review.

Failure Modes

Resolution fails closed when a resource is unbound, a kit has no published version, the caller is not authorized, or a required asset is unavailable. Publication fails with structured remediation when logo/font references or mandatory contrast are invalid. Validation returns explicit errors for claim, qualifier, CTA, language, asset, and snapshot-governance violations.

Debugging

Confirm the organization and consumer resource binding first, then inspect the resolved version ID and asset readiness. For publication refusal, follow the returned issue paths under visual.logos, visual.typography, or visual.palette; confirm the selected IDs exist in the version's own assets. If a consumer cannot fetch an asset, confirm resolve returned an absolute URL for the current Brand environment. Generation records should retain the exact version ID so the governing snapshot can be reproduced.

Use It

Open Topolo Brand for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-brand --json
topolo actions --service topolo-brand --json
topolo actions capabilities --service topolo-brand --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

1. Confirm the active identity and organization with topolo whoami --json.
2. Discover Topolo Brand and select one published action rather than guessing a route.
3. Inspect its input/output schemas and published example.
4. Validate and plan the exact payload; obtain confirmation for a mutation.
5. Execute and perform every published verification step.

Change Log / Verification

• Reconciled logo editing, asset URL portability, and publication governance against Brand staging source abd31ec9a88d on 2026-07-31. The Visual workbench now assigns real uploaded logo assets; drafts accept app-relative asset paths; resolve expands them per environment; and publication blocks missing/wrong-kind asset references plus mandatory foreground/primary contrast failures with structured 422 issues.

• Reconciled this page against exact Brand development/staging 253c651cfcedac77721f5719635644d42db6c2d6 on 2026-07-30. Added the implemented export, erasure, daily retention, pseudonymization, and governed R2 deletion boundary; corrected the published action count from 19 to 24. Exact staging API 9e999e10-6f7a-43b5-a809-e8a348037e54 and web a77726f0-66f8-4aa5-83b1-f053b3dadb77 are healthy, and the live canary proved scoped retention/erasure without changing the existing default workspace.

• Reconciled this page against apps/TopoloBrand origin/staging 159b05ec5865 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

• 2026-07-17: documented persisted Brand workspaces, Auth resource synchronization, and the shared catalog-owned application icon.

• 2026-07-16: documented canonical development, staging, and production provisioning plus the shared marketplace and action contract.

• 2026-07-15: documented the concern-split control/content/assets/audit storage topology and authoritative content-owned publication state.

• 2026-07-15: documented the canonical Brand boundary, immutable version contract, governed assets, read-only consumer model, and validation behavior.