Capabilities

Fluent's capability system provides runtime discovery of what the server supports. The fluent_get_capabilities tool and the fluent://core/capabilities resource are the primary entry points.

Contract Version

The current contract version is:

2026-04-05.fluent-core-v1.31

Clients and packages declare the minimum contract version they support. Capability discovery is the source of truth for the active version.

Required Fields

Every fluent_get_capabilities response includes:

Field	Purpose
contractVersion	The active contract version string
backendMode	Runtime mode (hosted, local, etc.)
availableDomains	Domains that can be enabled
enabledDomains	Domains currently enabled
readyDomains	Domains that are enabled and onboarded
onboarding.core	Core onboarding state
onboarding.domains	Per-domain onboarding state
profile.displayName	User's display name
profile.timezone	User's timezone

Additive Fields

Field	Purpose
deploymentTrack	cloud or oss
storageBackend	d1-r2, sqlite-fs, or postgres-s3
toolDiscovery	Workflow-oriented tool groupings and starter hints

Domain Lifecycle

Each domain passes through these states:

available  -->  enabled  -->  ready
                  |
                  v
              disabled

• available: The domain exists but has not been turned on
• enabled: The domain is active but onboarding may not be complete
• ready: The domain is enabled, onboarded, and fully usable
• disabled: The domain was enabled but has been turned off

Use fluent_enable_domain to move from available to enabled. The assistant should not auto-enable a disabled domain.

Onboarding

Onboarding is separate from lifecycle state. A domain can be enabled but not yet ready if onboarding is incomplete.

The onboarding flow:

1. fluent_enable_domain -- turn the domain on
2. fluent_begin_domain_onboarding -- start the onboarding questionnaire
3. Collect and save domain-specific preferences
4. fluent_complete_domain_onboarding -- mark onboarding done

Once complete, the domain appears in readyDomains.

Tool Discovery

The toolDiscovery section in capabilities provides:

{
  "canonicalRegistry": "tools/list",
  "note": "Use toolDiscovery groups as workflow hints, but tools/list is authoritative",
  "groups": {
    "meals_planning": ["meals_generate_plan", "meals_accept_plan_candidate", ...],
    "meals_shopping": ["meals_generate_grocery_plan", "meals_prepare_order", ...],
    "health_fitness": ["health_get_context", "health_upsert_block", ...],
    "style": ["style_get_context", "style_analyze_purchase", ...]
  }
}

These groups are guidance only. The MCP tools/list endpoint remains the authoritative registry.

Optional Capabilities

Fluent tracks feature flags as optional capabilities. These indicate what the server supports beyond the base contract:

Capability	Domain	Purpose
structured_content	Core	Structured content support
grocery_intents	Meals	Grocery intent tracking
domain_events	Core	Audit event logging
profile_resources	Core	Profile as MCP resource
meal_preferences	Meals	Dietary preferences
plan_history	Meals	Historical plan access
grocery_plan	Meals	Grocery plan generation
plan_generation	Meals	AI plan generation
calendar_aware_planning	Meals	Calendar-integrated planning
grocery_plan_actions	Meals	Grocery plan action state
inventory_batch_updates	Meals	Bulk inventory updates
inventory_hard_delete	Meals	Permanent inventory item removal
grocery_order_preflight	Meals	Order reconciliation
grocery_pantry_sufficiency_confirmation	Meals	Pantry-first order confirmation
grocery_purchase_carry_forward	Meals	Durable purchase coverage
confirmed_order_sync	Meals	Retailer order sync
tool_discovery_hints	Core	Workflow tool groupings
tool_list_fallback	Meals	Eager fallback directory
ingredient_form_groups	Meals	Ingredient grouping
style_profile	Style	Style profile reads
style_context	Style	Style context reads
style_purchase_analysis	Style	Purchase analysis
style_onboarding_summary	Style	Onboarding state
style_media_roles	Style	Typed media roles
style_media_delivery	Style	Image delivery
style_visual_bundle	Style	Visual bundle retrieval
style_item_status	Style	Item lifecycle status
style_item_profile_writes	Style	Descriptor writes
style_item_provenance	Style	Provenance reads
style_evidence_gaps	Style	Evidence gap detection
style_descriptor_backlog	Style	Enrichment queue
style_wardrobe_analysis	Style	Wardrobe gap analysis
style_descriptor_enrichment	Style	Descriptor enrichment
style_comparator_identity	Style	Comparator key model
style_comparator_coverage	Style	Coverage-aware analysis
health_preferences	Health	Training preferences
health_block_programming	Health	Block-based programming
health_today_resolution	Health	Today's workout resolution
health_block_reviews	Health	Weekly block reviews
health_workout_logging	Health	Workout logging
health_body_metrics	Health	Body metric tracking

Version Policy

• Changes after the freeze point must be additive only
• Breaking changes require package updates before release
• Clients must verify contractVersion against their minimum supported version
• fluent_get_capabilities is always the first tool to call