Skip to main content
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

EnvelopePurposeMust not do
Mintlify docsTeach humans and agents the primitive-first model.Claim docs make a package installable.
Agent skillTell Codex, Cursor, Claude, or Eve how to use the SDK and CLI.Redefine SDK primitives or bypass validation.
Plugin wrapperBundle the skill, references, validation script, optional MCP, and host manifest.Become a separate app model.
MCP configAdd live account, preview, publisher, or registry operations when enabled.Be required for local artifact creation.
Eve sandbox exportReturn validated exported artifacts for review.Install live sandbox output into production.
Registry handoffCarry 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.