# Brand Kit

## Status

The current working tree implements Brand Kit as a real workspace-owned domain
under `app/brand/` with `/v1/brand` REST routes, frontend brand-kit feature
modules, TypeScript/Python SDK resources, MCP brand tools, and an n8n
`MediaBrandKit` node. Authoritative PostgreSQL migrations, RLS runtime
certification, Docker/Hugging Face runtime verification, and final production
certification remain deferred until all planned product phases are complete.

## Domain model

`BrandKit` and `BrandKitVersion` are the canonical records. A kit owns versions
through `brand_kit_versions`, includes workspace/creator ownership fields, and
tracks `status`, timestamps, and an `active_version_id`. Versions store bounded
branding fields such as colors, fonts, voice/tone metadata, asset references,
watermark settings, and a `metadata` JSON column mapped safely away from the
SQLAlchemy reserved `metadata` attribute.

## API

| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/v1/brand` | List workspace brand kits with active version metadata. |
| `POST` | `/v1/brand` | Create a workspace brand kit. |
| `PATCH` | `/v1/brand/{brand_kit_id}` | Update a workspace brand kit. |
| `DELETE` | `/v1/brand/{brand_kit_id}` | Delete a workspace brand kit. |

`POST /v1/brand` accepts `name`, optional `description`, and `initial_version`
payload data. The response surface returns the kit plus its current
`active_version_id`; it does not expose invitation tokens or secret fields.

Version-specific brand-kit routes are **not exposed** in the current backend
contract. Python and TypeScript SDKs therefore fail closed with
`NotImplementedError` for `get_version` and `create_version` instead of
inventing endpoints.

## Frontend

The frontend uses `/v1/brand` through `frontend/features/brand-kits/api/index.ts`.
Brand kits appear in workspace settings navigation with `permission: "admin"`,
and capability discovery treats the brand area as active when the backend
advertises the expected routes.

## SDK

Both official SDKs use `/v1/brand` for list/get/create/update/delete operations.
The Python client is defined in `sdk/python/media_platform/brand_kits.py`, and
the TypeScript client is defined in `sdk/typescript/src/resources/brand-kits.ts`.
Static contract tests verify route paths, request bodies, and fail-closed
versioned-operation behavior.

## MCP and n8n

MCP registers narrow typed brand tools through `app/mcp/tools/brand.py` and
`app/mcp/server.py`. The official n8n `MediaBrandKit` node consumes the shared
MediaRouter SDK/credential boundary; no provider credentials or raw brand
documents are exposed to n8n transports.

## Security and runtime

Brand kit routes reuse the existing API-key authentication, scoped workspace
context, and structured audit boundary. Sensitive fields remain backend-only.
PostgreSQL FORCE RLS, migration ordering, and provider-facing certification are
intentionally deferred to the final production certification phase.