Begin with a capability, not a vendor name
ContractsIntegrations defines provider-agnostic specifications, connections, authentication/transport, secret resolution, health and capability interfaces such as LLM, embeddings, email, vector stores and storage. The provider integration packages implement concrete boundaries. Start from the operation your product needs, find its capability contract, then inspect the adapter that claims that exact surface. A provider package name or a registered catalog record does not establish that every provider product feature is supported or enabled for an account.
Keep execution mode separate from credentials
ProviderSpec describes runtime targets, routing policies, leases, receipts, observations and comparison evidence. ProviderRuntime normalizes those records for host use. The README distinguishes managed/local/hybrid runtime targets from credential ownership modes such as BYOK, ephemeral or none. Preserve that distinction in configuration and UI so a credential selection does not silently choose an execution location. Redact credential-like resolver fields before logging while retaining non-secret mode and capability information needed for diagnosis.
Inspect the whole connection lifecycle
A useful integration guide should follow connection creation, required scopes/capabilities, secret references, readiness, one operation and its returned receipt. Reconnection, revoked access, rate limits, stale health and ambiguous effects belong to the same story. Provider observations can inform routing and budget decisions, but source metadata still needs the host’s current evidence. For capabilities such as meeting capture or external publication, domain consent and current authorization remain prerequisites even when the provider SDK is available.
Follow a practical path.
Select the exact interface
Read the consumer’s provider contract and list the methods or capability references it needs. Open the matching integration package export map and README rather than importing a broad implementation bundle by default.
Bind a scoped connection
Identify the credential owner, runtime target, secret resolver and required permissions. Follow how the product checks readiness and handles a missing capability or disconnected account before offering an action.
Inspect a provider result
Trace the adapter response into the normalized receipt and domain outcome. Use the owning fixture for denial, throttling and uncertain completion, then qualify real provider behavior in the intended environment before advertising it as available.