> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budscollab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Primitive catalog

> The UI, surface, capability, safety, and distribution primitives used by BudsCollab apps.

The primitive catalog is the source vocabulary for BudsCollab apps. Treat it as
the atomic UI and capability catalog: app builders, Eve, Codex skills, CLI
scaffolds, docs, and registry review should all point back to this same model.

The catalog has six layers:

* UI primitives: cards, rows, badges, app icons, metrics, and action buttons.
* Theme primitives: room-managed tokens, primitive hooks, app icon families,
  widget surfaces, wall frames, note presets, and score evidence.
* Surface primitives: widget, fullscreen, dock, overlay, and chat panel.
* Capability primitives: host data, connector reads, room state, safe actions,
  collaboration presence, and sandboxed code.
* Safety primitives: permission boundary, renderer boundary, provenance,
  network policy, write policy, and review report.
* Distribution primitives: saved widget, published widget, published wall, full
  app, sandbox project, and developer-owned repo.

The SDK source of truth is `SDK_PRIMITIVE_LAYER_CATALOG`. Each layer points to
the concrete catalogs used by validation:

* UI: `SDK_JSON_RENDER_COMPONENT_ALLOWLIST`
* Theme: `BUDSCOLLAB_ROOM_THEME_COMPONENT_PRIMITIVES`,
  `BUDSCOLLAB_ROOM_THEME_DESIGN_SYSTEM_REPORT`, and
  `BUDSCOLLAB_ROOM_THEME_NOTION_BENCHMARK_REPORT`
* Surfaces: `APP_CREATOR_SURFACE_CATALOG`
* Capabilities: `APP_CREATOR_CAPABILITY_CATALOG`
* Safety: `APP_CREATOR_SANDBOX_SAFETY_GATES` plus package validation.
* Distribution: `APP_CREATOR_DISTRIBUTION_TARGET_CATALOG` and
  `SDK_DISTRIBUTION_LIFECYCLE_CATALOG`.

## How to use it

Start with the smallest primitive set that can express the app:

1. Pick surfaces: widget, fullscreen, dock, overlay, or chat panel.
2. Pick UI primitives: cards, rows, badges, metrics, forms, and action buttons.
3. Bind Theme primitives: inherit room tokens, use host card and app-icon hooks,
   and preserve widget, wall, and note preset controls.
4. Pick capabilities: host data, connector reads, room state, safe actions, or
   collaboration presence.
5. Pick safety gates: permission boundary, renderer boundary, provenance,
   network policy, write policy, and review report.
6. Pick distribution target: personal widget, full app, sandbox project, or
   developer-owned repo.

Only move to sandboxed custom code when the app cannot be expressed with
host-rendered primitives. Even then, the package still declares surfaces,
capabilities, safety gates, and distribution target with the same SDK contract.
The package should also keep room Theme as the design-system manager: generated
or developer-owned BudsApps inherit Theme tokens, register a stable app identity
and icon family, and carry 8+ design-system and Notion benchmark score evidence
before review.