> ## 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.

# Atomic UI composability

> Why every app, plugin package, agent skill, Eve export, and registry handoff starts from the same primitive catalog.

BudsCollab composability starts with the atomic UI catalog. Builders choose
primitives first, then wrap the validated SDK artifact for the environment that
needs it.

A plugin package should not introduce a second product model. It can bundle
skills, docs, scripts, optional MCP, and host-specific manifest files, but the
thing being produced for BudsCollab is still a primitive-based app artifact.

## The rule

Every BudsCollab app and plugin package must declare the same primitive layers:

* UI primitives from the atomic UI catalog.
* Surface primitives: widget, fullscreen, dock, overlay, or chat panel.
* Capability primitives: room state, connector reads, safe actions, presence,
  or sandboxed code.
* Safety primitives: renderer boundary, permission boundary, provenance,
  network policy, write policy, and review evidence.
* Distribution primitives: personal widget, full app, agent plugin package,
  Eve sandbox export, or registry handoff.

The checked contract is `primitive-composability-contract.json`. It connects the
Mintlify docs, agent skills, plugin wrappers, optional MCP config, Eve sandbox
exports, and registry handoff back to `SDK_PRIMITIVE_LAYER_CATALOG` and the
same review-gated install posture.

## What belongs in each envelope

| Envelope           | Purpose                                                                           | Must not do                                                  |
| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Mintlify docs      | Teach humans and agents the primitive-first model.                                | Claim docs make a package installable.                       |
| Agent skill        | Tell Codex, Cursor, Claude, or Eve how to use the SDK and CLI.                    | Redefine SDK primitives or bypass validation.                |
| Plugin wrapper     | Bundle the skill, references, validation script, optional MCP, and host manifest. | Become a separate app model.                                 |
| MCP config         | Add live account, preview, publisher, or registry operations when enabled.        | Be required for local artifact creation.                     |
| Eve sandbox export | Return validated exported artifacts for review.                                   | Install live sandbox output into production.                 |
| Registry handoff   | Carry review policy, install blockers, and future acceptance payloads.            | Claim marketplace acceptance before signing and host policy. |

## Mintlify is part of the agent surface

Mintlify docs should be the canonical source because they serve both humans and
agents. The public docs should expose `llms.txt`, `skill.md`,
`/.well-known/agent-skills/index.json`, and `/.well-known/agent-card.json` once
hosted on the canonical domain.

Until those paths are deployed and verified, BudsCollab can claim the docs are
Mintlify-ready and checked locally. Hosted docs, agent discovery, and install
permission require separate verification.

## Decision model

Build in this order:

1. Express the experience with atomic UI primitives.
2. Add only the surfaces the app needs.
3. Request named capabilities instead of importing host internals.
4. Attach safety gates before packaging.
5. Validate with `@budscollab/cli`.
6. Add a plugin wrapper only when the developer workflow needs portable agent
   instructions, docs, scripts, or optional MCP.
7. Submit registry handoff artifacts only after the local review report is
   clean enough to explain remaining install blockers.

This keeps the promise honest: everything in BudsCollab is safely composable
because the app model is primitive-first, while plugins, skills, MCP, Eve, and
registry APIs are controlled ways to create, explain, validate, or distribute
that same app model.