How to use profile-atoms

The catalog

curl https://profile-atoms.com/exports/catalog.json
curl https://profile-atoms.com/profiles/jmfamily-profiles-developer.json
curl https://profile-atoms.com/schemas/profile-atom-v1.json

Schema

Every profile validates against /schemas/profile-atom-v1.json (Draft 2020-12). The schema is the contract; the on-disk serialization is JSON, but other forms (YAML, TOML) are equivalent representations.

Required fields

• schema — const reference to this catalog's schema URL.
• canonical_name — <namespace>/profiles/<slug> globally-unique identifier.
• version — semver.
• authored_by — signing key identifier.
• description — human-readable description (≤ 1000 chars).
• role_packs — ordered array of {ref, version, priority}. At least one required.
• default_persona, default_theme — refs to atoms in persona-atoms / theme-atoms.
• default_budget — {per_action, per_session, per_day, on_cap_hit}; on_cap_hit ∈ {warn, require_confirm, deny}.
• available_identities — set of refs (at least one); contexts pick from this set.
• update_policy — {auto_upgrade, notification, diff_visualization}; diff_visualization ∈ {required, optional, none}.
• trust_requirements — per-atom-type signing gates.

Optional fields

• signed_by — additional endorsement signatures.
• policy_stack, governance_stack, available_channels, knowledge_sources, default_workflows — sets that may be empty.
• extends — parent profile reference (single-level or chained).

Reference shape

All cross-catalog references use:

{ "ref": "<namespace>/<type>/<slug>", "version": "<semver>" }

The role_packs array additionally carries a priority (integer, lower = higher priority) to break vocabulary collisions.

Composition semantics

How a profile's referenced atoms combine at activation (see design doc for the full model):

• Vocabulary (role-packs) — all in scope; priority breaks ties.
• Policies — intersection; every policy must approve.
• Governance — union of strictest requirements.
• Persona / theme / budget — defaults; session-scoped overrides allowed where the policy stack permits.
• Identities / channels — situational contexts pick subsets from the profile's set; cannot exceed.

What's NOT in a profile

Not the secrets engine state. Not the cache. Not the transcript history. Not the active model. Not LLM provider credentials. Not the active identity or active channels (those live on the situational context). Not session state. See design for the full boundary.

Caching

The catalog is cached for 60s at the edge. Individual profile files for 5 minutes. The schema for 1 hour. CORS is open.