@portpowered/reference-data 0.4.5 → 0.4.7

package/generated/public/docs/for-ai/api-catalog.md

@@ -0,0 +1,123 @@
+# Port OS API catalog: compact reference
+
+For a new connection, read [authentication and DCR/CIMD](/docs/for-ai/guides/authentication-and-dcr.md), then [the REST quickstart](/docs/for-ai/guides/quickstart.md). Registration grants no device access. Discover the issuer and endpoints; choose REST or MCP before consent, use PKCE, validate the callback, then exchange its code. REST uses the issuer as its OAuth resource; MCP uses its /mcp resource.
+
+Operation scopes and resource permissions both apply. [Authorization rules](/docs/for-ai/guides/authorization-rules.md) explain consent, sharing, evaluation and denial. Bearer-session alternatives describe signed-in user sessions; they do not bypass delegated-token scopes.
+
+This index lists public operations, parameter names and top-level JSON keys. Required, conditional and nested fields remain in each linked operation/schema contract. Read only the contract needed for your next request. [Capability index](/docs/for-ai/capability-interfaces.md).
+
+To request the complete rendered catalog, fetch `/api/?full=1` with an HTML-compatible Accept header. [Full OpenAPI YAML](/docs/references/openapi.yaml) is available for comprehensive lookup and SDK generation.
+
+| Operation contract | OAuth scopes / conditional scopes | Parameters | Top-level JSON body keys |
+| --- | --- | --- | --- |
+| [GET /.well-known/jwks.json](/docs/for-ai/operations/getJWKS.md) | Public | — | — |
+| [GET /.well-known/oauth-authorization-server](/docs/for-ai/operations/getOAuthAuthorizationServerMetadata.md) | Public | — | — |
+| [GET /.well-known/oauth-protected-resource](/docs/for-ai/operations/getOAuthProtectedResourceMetadata.md) | Public | — | — |
+| [GET /.well-known/oauth-protected-resource/mcp](/docs/for-ai/operations/getMCPOAuthProtectedResourceMetadata.md) | Public | — | — |
+| [GET /.well-known/openid-configuration](/docs/for-ai/operations/getOpenIDConfiguration.md) | Public | — | — |
+| [DELETE /{namespace}/{principalType}/{principalId}](/docs/for-ai/operations/deletePrincipal.md) | OAuth (no scope) | path:namespace (required), path:principalType (required), path:principalId (required) | — |
+| [DELETE /{namespace}/{principalType}/{principalId}/access-control-rules/{ruleId}](/docs/for-ai/operations/deleteAccessControlRule.md) | OAuth (no scope) | path:namespace (required), path:principalType (required), path:principalId (required), path:ruleId (required) | — |
+| [GET /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}](/docs/for-ai/operations/getEndpointGroup.md) | group:read | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required), query:expand, query:forceDeviceAttributeQuery | — |
+| [DELETE /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}](/docs/for-ai/operations/deleteEndpointGroup.md) | group:manage | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required), header:If-Match (required) | — |
+| [POST /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/add-members](/docs/for-ai/operations/addEndpointGroupMembers.md) | group:manage | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required), header:If-Match (required) | memberEndpointIds |
+| [POST /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/remove-members](/docs/for-ai/operations/removeEndpointGroupMembers.md) | group:manage | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required), header:If-Match (required) | memberEndpointIds |
+| [POST /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/set-name](/docs/for-ai/operations/setEndpointGroupName.md) | group:manage | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required), header:If-Match (required) | name |
+| [DELETE /{namespace}/{principalType}/{principalId}/flow-runs/{runId}](/docs/for-ai/operations/deleteFlowRun.md) | See session/security contract | path:namespace (required), path:principalType (required), path:principalId (required), path:runId (required) | — |
+| [GET /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs](/docs/for-ai/operations/queryFlowRuns.md) | See session/security contract | path:namespace (required), path:principalType (required), path:principalId (required), path:flowId (required), query:pageToken, query:maxResults, query:expand, query:nextToken | — |
+| [POST /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs](/docs/for-ai/operations/createFlowRun.md) | See session/security contract | path:namespace (required), path:principalType (required), path:principalId (required), path:flowId (required) | flowRun |
+| [POST /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/messages](/docs/for-ai/operations/upsertFlowRunMessage.md) | See session/security contract | path:namespace (required), path:principalType (required), path:principalId (required), path:flowId (required), path:runId (required) | message, target |
+| [POST /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/set-status](/docs/for-ai/operations/setFlowRunStatus.md) | See session/security contract | path:namespace (required), path:principalType (required), path:principalId (required), path:flowId (required), path:runId (required) | status |
+| [DELETE /{namespace}/{principalType}/{principalId}/group-routes/{groupId}](/docs/for-ai/operations/deleteGroupRoute.md) | group:manage | path:namespace (required), path:principalType (required), path:principalId (required), path:groupId (required) | — |
+| [GET /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}](/docs/for-ai/operations/getSubscription.md) | subscription:read | path:namespace (required), path:principalType (required), path:principalId (required), path:subscriptionId (required), query:expand | — |
+| [PATCH /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}](/docs/for-ai/operations/patchSubscription.md) | subscription:write | path:namespace (required), path:principalType (required), path:principalId (required), path:subscriptionId (required) | name |
+| [DELETE /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}](/docs/for-ai/operations/deleteSubscription.md) | subscription:write | path:namespace (required), path:principalType (required), path:principalId (required), path:subscriptionId (required) | — |
+| [DELETE /{namespace}/{principalType}/{principalId}/tokens/{tokenId}](/docs/for-ai/operations/invalidateToken.md) | OAuth (no scope) | path:tokenId (required), path:namespace (required), path:principalType (required), path:principalId (required) | — |
+| [GET /{namespace}/{principalType}/{principalId}/views/{viewId}](/docs/for-ai/operations/getView.md) | OAuth (no scope) | path:namespace (required), path:principalType (required), path:principalId (required), path:viewId (required), query:expand | — |
+| [PUT /{namespace}/{principalType}/{principalId}/views/{viewId}](/docs/for-ai/operations/updateView.md) | OAuth (no scope) | path:namespace (required), path:principalType (required), path:principalId (required), path:viewId (required) | positions, schemaVersion, title, widgets |
+| [DELETE /{namespace}/{principalType}/{principalId}/views/{viewId}](/docs/for-ai/operations/deleteView.md) | OAuth (no scope) | path:namespace (required), path:principalType (required), path:principalId (required), path:viewId (required) | — |
+| [DELETE /{principalType}/{principalId}/flows/{flowId}](/docs/for-ai/operations/deleteFlow.md) | See session/security contract | path:principalType (required), path:principalId (required), path:flowId (required) | — |
+| [GET /access-control-rules](/docs/for-ai/operations/getAccessControlRules.md) | OAuth (no scope) | query:owner (required), query:nextToken, query:maxResults, query:expand | — |
+| [POST /access-control-rules](/docs/for-ai/operations/upsertAccessControlRule.md) | OAuth (no scope) | — | effect, id, identity, operation, resource |
+| [POST /access-control-rules/evaluate](/docs/for-ai/operations/evaluateAccessControlRule.md) | OAuth (no scope) | — | entities, operation, requesterContext, resourceContext |
+| [GET /auth-links](/docs/for-ai/operations/enumerateAuthLinks.md) | OAuth (no scope) | query:expand, query:nextToken, query:maxResults | — |
+| [POST /auth-links](/docs/for-ai/operations/upsertAuthLink.md) | OAuth (no scope) | — | authLink |
+| [DELETE /auth-links](/docs/for-ai/operations/deleteAuthLink.md) | OAuth (no scope) | — | id |
+| [POST /auth-links/establish](/docs/for-ai/operations/establishAuthLink.md) | See session/security contract | — | apiKey, applePushNotificationDeviceToken, authLinkId, oauthTokens, pluginId, usernamePassword |
+| [POST /auth-links/refresh](/docs/for-ai/operations/refreshAuthLinkToken.md) | See session/security contract | — | authLinkId |
+| [POST /auth/callback](/docs/for-ai/operations/handleOAuthCallback.md) | Public | — | code, id_token, state, user |
+| [POST /auth/device-authorization](/docs/for-ai/operations/deviceAuthorize.md) | See session/security contract | — | client_id, scope |
+| [POST /auth/raise](/docs/for-ai/operations/raiseAnonymousPrincipal.md) | Public | — | anonymous_refresh_token, subject_token, subject_token_type |
+| [POST /auth/revoke](/docs/for-ai/operations/revokeOAuthGrant.md) | Public | — | client_id, token |
+| [POST /auth/token](/docs/for-ai/operations/generateToken.md) | Public | — | client_id, client_secret, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope |
+| [POST /discovery](/docs/for-ai/operations/synchronizeRoutes.md) | See session/security contract | — | authLinkIdentity, groupRoutes, pluginIdentity, relationships, routes |
+| [GET /endpoint-groups](/docs/for-ai/operations/enumerateEndpointGroups.md) | group:read | query:enablement, query:owner (required), query:nextToken, query:maxResults, query:expand, query:forceDeviceAttributeQuery | — |
+| [POST /endpoint-groups](/docs/for-ai/operations/createEndpointGroup.md) | group:manage | — | item |
+| [POST /endpoint-groups-manage](/docs/for-ai/operations/endpointGroupsManage.md) | group:manage | header:Idempotency-Key (required) | operations, validateOnly |
+| [POST /endpoint-query](/docs/for-ai/operations/endpointQuery.md) | endpoint:read; groupId: group:read | — | expand, forceDeviceQuery, paginationContext, query |
+| [GET /endpoint-simulators](/docs/for-ai/operations/enumerateSimulators.md) | See session/security contract | query:owner, query:maxResults, query:nextToken, query:expand | — |
+| [POST /endpoint-simulators](/docs/for-ai/operations/upsertSimulator.md) | See session/security contract | — | configuration, device_type, id, name, state |
+| [DELETE /endpoint-simulators](/docs/for-ai/operations/deleteSimulator.md) | See session/security contract | — | id |
+| [GET /endpoints](/docs/for-ai/operations/enumerateEndpoints.md) | endpoint:read | query:enablement, query:owner, query:id, query:type, query:serialNumber, query:nextToken, query:maxResults, query:expand, query:forceDeviceAttributeQuery | — |
+| [POST /endpoints](/docs/for-ai/operations/upsertEndpoint.md) | endpoint:write | — | id, name, type |
+| [PATCH /endpoints](/docs/for-ai/operations/modifyEndpoint.md) | endpoint:write | — | enablement, id, mergeInto, name, type |
+| [DELETE /endpoints](/docs/for-ai/operations/deleteEndpoint.md) | endpoint:write | — | id |
+| [GET /event-dead-letters](/docs/for-ai/operations/enumerateEventDeadLetters.md) | See session/security contract | query:nextToken, query:maxResults, query:query, query:expand | — |
+| [GET /event-dead-letters/{id}](/docs/for-ai/operations/getEventDeadLetter.md) | See session/security contract | path:id (required), query:expand | — |
+| [DELETE /event-dead-letters/{id}](/docs/for-ai/operations/deleteEventDeadLetter.md) | See session/security contract | path:id (required) | — |
+| [POST /event-dead-letters/{id}/redrives](/docs/for-ai/operations/redriveEventDeadLetter.md) | See session/security contract | path:id (required) | — |
+| [POST /events](/docs/for-ai/operations/createSyntheticEvent.md) | See session/security contract | — | body, endpoint, header, requestId |
+| [GET /events/receipts/{receiptId}](/docs/for-ai/operations/getEventReceipt.md) | See session/security contract | path:receiptId (required), query:expand | — |
+| [GET /flow-node-specifications](/docs/for-ai/operations/enumerateFlowNodeSpecifications.md) | See session/security contract | query:nextToken, query:maxResults, query:expand | — |
+| [GET /flow-nodes](/docs/for-ai/operations/enumerateFlowNodes.md) | See session/security contract | query:expand, query:nextToken, query:maxResults | — |
+| [POST /flow-nodes](/docs/for-ai/operations/createFlowNode.md) | See session/security contract | — | flow |
+| [DELETE /flow-nodes](/docs/for-ai/operations/deleteFlowNode.md) | See session/security contract | — | id |
+| [GET /flows](/docs/for-ai/operations/queryFlows.md) | See session/security contract | query:owner, query:id, query:nextToken, query:maxResults, query:expand | — |
+| [POST /flows](/docs/for-ai/operations/upsertFlow.md) | See session/security contract | — | flow |
+| [POST /flows/trigger](/docs/for-ai/operations/triggerFlow.md) | See session/security contract | — | flow, triggers |
+| [GET /group-relationships](/docs/for-ai/operations/enumerateGroupRelationships.md) | group:read | query:owner (required), query:groupId, query:routeId, query:endpointId, query:nextToken, query:maxResults, query:expand | — |
+| [GET /group-routes](/docs/for-ai/operations/enumerateGroupRoutes.md) | group:read | query:owner (required), query:nextToken, query:maxResults, query:expand | — |
+| [POST /integration-requests](/docs/for-ai/operations/requestFutureIntegration.md) | Public | — | consent, email, pluginId |
+| [POST /messages](/docs/for-ai/operations/sendMessage.md) | message:send | — | message, responseType, target |
+| [POST /messages-gateway](/docs/for-ai/operations/pushToMessageGateway.md) | OAuth (no scope) | — | auth-token, body, context, correlationToken, endpoint, header, ownerId, secrets, target, type |
+| [POST /messages/send](/docs/for-ai/operations/sendMessageLegacyAlias.md) | message:send | — | message, responseType, target |
+| [GET /metrics](/docs/for-ai/operations/getMetrics.md) | Public | — | — |
+| [GET /oauth-clients](/docs/for-ai/operations/enumerateOAuthClients.md) | OAuth (no scope) | query:nextToken, query:maxResults, query:expand | — |
+| [POST /oauth-clients](/docs/for-ai/operations/createOAuthClient.md) | OAuth (no scope) | — | allowedOrigins, clientName, clientUri, clientUriLocalized, contacts, grantTypes, jwks, jwksUri, logoUri, logoUriLocalized, policyUri, policyUriLocalized, redirectUris, responseTypes, scope, scopes, softwareId, softwareVersion, tokenEndpointAuthMethod, tokenEndpointAuthSigningAlg, tosUri, tosUriLocalized |
+| [GET /oauth/authorization-request](/docs/for-ai/operations/getPendingOAuthConsent.md) | See session/security contract | query:request_id (required) | — |
+| [GET /oauth/authorize](/docs/for-ai/operations/beginOAuthAuthorization.md) | Public | query:client_id (required), query:redirect_uri (required), query:response_type (required), query:scope (required), query:state (required), query:resource (required), query:code_challenge (required), query:code_challenge_method (required) | — |
+| [POST /oauth/authorize](/docs/for-ai/operations/completeOAuthConsent.md) | See session/security contract | — | approved, request_id, scope |
+| [POST /oauth/authorize-device](/docs/for-ai/operations/authorizeDevice.md) | OAuth (no scope) | — | scopes, user_code |
+| [POST /oauth/generate-code](/docs/for-ai/operations/generateOAuthCode.md) | OAuth (no scope) | — | client_id, code_challenge, code_challenge_method, redirect_uri, scopes, state |
+| [POST /oauth/register](/docs/for-ai/operations/registerDynamicOAuthClient.md) | Public | — | client_name, client_uri, grant_types, redirect_uris, response_types, scope, software_id, software_statement, software_version, token_endpoint_auth_method |
+| [POST /oauth/validate-request](/docs/for-ai/operations/validateOAuthRequest.md) | See session/security contract | — | client_id, code_challenge, code_challenge_method, redirect_uri, scopes |
+| [GET /oauth/verify-device](/docs/for-ai/operations/verifyDevice.md) | Public | query:user_code (required) | — |
+| [GET /ping](/docs/for-ai/operations/ping.md) | Public | — | — |
+| [POST /plugin-auth-code-exchange](/docs/for-ai/operations/pluginAuthCodeExchange.md) | OAuth (no scope) | — | pluginAuthenticationData, pluginId, principalId |
+| [POST /plugin-auth-code-link](/docs/for-ai/operations/pluginAuthCodeLink.md) | OAuth (no scope) | — | pluginId, principalId |
+| [POST /plugin-auth-multifactor-exchange](/docs/for-ai/operations/pluginAuthMultifactorExchange.md) | OAuth (no scope) | — | pluginAuthenticationData, pluginId, principalId |
+| [GET /plugins](/docs/for-ai/operations/enumeratePlugins.md) | OAuth (no scope) | query:expand, query:id, query:nextToken, query:maxResults | — |
+| [POST /plugins](/docs/for-ai/operations/upsertPluginRequest.md) | OAuth (no scope) | — | applePushNotificationSecret, plugin, secretReferenceId |
+| [DELETE /plugins](/docs/for-ai/operations/deletePlugin.md) | OAuth (no scope) | — | id |
+| [POST /plugins/establish](/docs/for-ai/operations/establishPlugin.md) | See session/security contract | — | plugin |
+| [GET /port1/{principalType}/{principalId}/oauth-clients/{clientId}](/docs/for-ai/operations/getOAuthClient.md) | OAuth (no scope) | path:principalType (required), path:principalId (required), path:clientId (required), query:expand | — |
+| [PUT /port1/{principalType}/{principalId}/oauth-clients/{clientId}](/docs/for-ai/operations/updateOAuthClient.md) | OAuth (no scope) | path:principalType (required), path:principalId (required), path:clientId (required) | allowedOrigins, clientName, clientUri, clientUriLocalized, contacts, grantTypes, jwks, jwksUri, logoUri, logoUriLocalized, policyUri, policyUriLocalized, redirectUris, responseTypes, scope, scopes, softwareId, softwareVersion, tokenEndpointAuthMethod, tokenEndpointAuthSigningAlg, tosUri, tosUriLocalized |
+| [DELETE /port1/{principalType}/{principalId}/oauth-clients/{clientId}](/docs/for-ai/operations/deleteOAuthClient.md) | OAuth (no scope) | path:principalType (required), path:principalId (required), path:clientId (required) | — |
+| [DELETE /port1/{principalType}/{principalId}/secrets/{secretId}](/docs/for-ai/operations/deleteSecret.md) | OAuth (no scope) | path:principalType (required), path:principalId (required), path:secretId (required) | — |
+| [GET /principals](/docs/for-ai/operations/enumeratePrincipals.md) | OAuth (no scope) | query:expand, query:nextToken, query:maxResults | — |
+| [POST /principals](/docs/for-ai/operations/upsertPrincipal.md) | OAuth (no scope) | — | item |
+| [GET /routes](/docs/for-ai/operations/getRoutes.md) | endpoint:read | query:expand, query:nextToken, query:maxResults | — |
+| [POST /routes](/docs/for-ai/operations/upsertRoute.md) | endpoint:write | — | endpointId, id, interfaces, metadata, pluginId |
+| [DELETE /routes](/docs/for-ai/operations/deleteRoute.md) | endpoint:write | — | id |
+| [GET /secrets](/docs/for-ai/operations/enumerateSecrets.md) | OAuth (no scope) | query:id, query:owner, query:nextToken, query:maxResults, query:expand | — |
+| [POST /secrets](/docs/for-ai/operations/upsertSecret.md) | OAuth (no scope) | — | secret |
+| [GET /subscriptions](/docs/for-ai/operations/enumerateSubscriptions.md) | subscription:read | query:expand, query:nextToken, query:maxResults | — |
+| [POST /subscriptions](/docs/for-ai/operations/upsertSubscription.md) | subscription:write | — | subscription |
+| [GET /tokens](/docs/for-ai/operations/enumerateTokens.md) | OAuth (no scope) | query:nextToken, query:maxResults, query:expand | — |
+| [POST /tokens](/docs/for-ai/operations/createToken.md) | OAuth (no scope) | — | expires_in, label, scope, subject |
+| [POST /tuya/qrcode](/docs/for-ai/operations/generateTuyaQrCode.md) | Public | — | accessCode, authenticationUrl, clientId, schema |
+| [POST /tuya/validatetoken](/docs/for-ai/operations/validateTuyaLoginCode.md) | Public | — | authenticationUrl, clientId, loginCode, userCode |
+| [GET /views](/docs/for-ai/operations/enumerateViews.md) | OAuth (no scope) | query:nextToken, query:maxResults, query:expand | — |
+| [POST /views](/docs/for-ai/operations/createView.md) | OAuth (no scope) | — | positions, schemaVersion, title, widgets |
+| [POST /webhooks/github](/docs/for-ai/operations/handleGitHubWebhook.md) | Public | header:X-Hub-Signature-256 (required), header:X-GitHub-Delivery, header:X-GitHub-Event | — |
+| [POST /webhooks/google-cloud-scheduler](/docs/for-ai/operations/handleGoogleCloudSchedulerWebhook.md) | See session/security contract | — | flow_id, node_id |
+| [POST /webhooks/smartthings](/docs/for-ai/operations/handleSmartThingsWebhook.md) | OAuth (no scope) | — | — |

package/generated/public/docs/for-ai/capability-interfaces/brightness/1.0.md

@@ -10,6 +10,7 @@ Read scopes: endpoint:read. Inbound control scope: message:send. Resource permis
 
 ## Messages
 
+- [adjust-brightness](/docs/references/capability-interfaces/brightness/1.0/messages/adjust-brightness.yaml) (in): Adjust brightness by a signed number of percentage points. The endpoint must advertise this message separately from set-brightness.
 - [set-brightness](/docs/references/capability-interfaces/brightness/1.0/messages/set-brightness.yaml) (in): Use this exact payload schema.
 
 ## State attributes

package/generated/public/docs/for-ai/capability-interfaces/media-player/1.0.md

@@ -12,6 +12,7 @@ Read scopes: endpoint:read. Inbound control scope: message:send. Resource permis
 
 - [audio](/docs/references/capability-interfaces/media-player/1.0/messages/audio.yaml) (out): Use this exact payload schema.
 - [audio-stream](/docs/references/capability-interfaces/media-player/1.0/messages/audio-stream.yaml) (out): Use this exact payload schema.
+- [fast-forward](/docs/references/capability-interfaces/media-player/1.0/messages/fast-forward.yaml) (in): Begin provider-defined fast-forward playback. This does not seek by a specific duration; use skip-forward or seek for a known position change.
 - [next](/docs/references/capability-interfaces/media-player/1.0/messages/next.yaml) (in): Use this exact payload schema.
 - [pause](/docs/references/capability-interfaces/media-player/1.0/messages/pause.yaml) (in): Use this exact payload schema.
 - [play-audio](/docs/references/capability-interfaces/media-player/1.0/messages/play-audio.yaml) (in): Play a base64 encoded audio object on the endpoint. Requires audio output support; RTSP or SDP alone does not establish playback support.
@@ -20,7 +21,7 @@ Read scopes: endpoint:read. Inbound control scope: message:send. Resource permis
 - [play-uri](/docs/references/capability-interfaces/media-player/1.0/messages/play-uri.yaml) (in): Use this exact payload schema.
 - [previous](/docs/references/capability-interfaces/media-player/1.0/messages/previous.yaml) (in): Use this exact payload schema.
 - [rewind](/docs/references/capability-interfaces/media-player/1.0/messages/rewind.yaml) (in): Use this exact payload schema.
-- [search-and-play](/docs/references/capability-interfaces/media-player/1.0/messages/search-and-play.yaml) (in): Use this exact payload schema.
+- [search-and-play](/docs/references/capability-interfaces/media-player/1.0/messages/search-and-play.yaml) (in): Search for and play media by title or query using a service advertised by the endpoint. Omitting mediaType retains audio search behavior; video-only endpoints may default to video.
 - [seek](/docs/references/capability-interfaces/media-player/1.0/messages/seek.yaml) (in): Use this exact payload schema.
 - [skip-backward](/docs/references/capability-interfaces/media-player/1.0/messages/skip-backward.yaml) (in): Use this exact payload schema.
 - [skip-forward](/docs/references/capability-interfaces/media-player/1.0/messages/skip-forward.yaml) (in): Use this exact payload schema.

package/generated/public/docs/for-ai/guides/lighting.md

@@ -4,6 +4,22 @@ Start with authorized endpoint discovery and inspect capability declarations. A
 
 For one bulb, read its power/brightness/color message schemas in [the capability directory](/docs/for-ai/capability-interfaces.md). Use the exact namespace, version, message name, units and constraints returned. [The quickstart](/docs/for-ai/guides/quickstart.md) shows the generic dispatch envelope.
 
-For “all lights,” include explicitly authorized shared lights and the user-requested home/group scope. Complete pagination, exclude disabled/unavailable unsupported targets as documented and deduplicate nested groups. Do not broaden the set to every power-capable endpoint. Use the existing query/dispatch contract if it supports the selection; otherwise enumerate the fixed target set and report each result.
+For “all lights,” use [endpointQuery](/docs/for-ai/operations/endpointQuery.md): POST /endpoint-query with endpoint:read. Its results include readable shared endpoints from other owners. Start with the LIGHT and LIGHTBULB types below, then limit the results to the user's requested home or group.
 
-A batch can partially succeed. Report selected, accepted, failed and unresolved targets separately. Read fresh state before claiming all lights changed. A lost response does not justify repeating relative brightness adjustments. See [authorization rules](/docs/for-ai/guides/authorization-rules.md).
+```json
+{
+  "query": {
+    "or": [
+      {"match": {"key": "type", "value": "LIGHT"}},
+      {"match": {"key": "type", "value": "LIGHTBULB"}}
+    ]
+  },
+  "paginationContext": {"maxResults": 25}
+}
+```
+
+For a room, first resolve its full group ID using [group discovery](/docs/for-ai/guides/managing-groups.md). Intersect the type predicate with `{"match":{"key":"groupId","value":"<resolved-full-group-id>"}}` inside query.and. This additionally requires group:read and permission to read that group. A group filter uses its returned member endpoints; resolve the requested nested groups as needed and deduplicate full endpoint IDs. Reading a group does not grant control of its members.
+
+Repeat the same query, page size and authenticated grant with paginationContext.nextToken from each response. Continue until that token is absent, including after an empty page. Disabled endpoints are excluded by default. Inspect declared capabilities for the selected endpoints and exclude unsupported targets; do not broaden the selection to every power-capable plug or switch. Freeze the discovered target set before dispatch and report each result.
+
+A batch can partially succeed. Report selected, accepted, failed and unresolved targets separately. For fresh readback, repeat endpointQuery with expand:["interfaces.attributes"] and forceDeviceQuery:true. Inspect observation sample times and response errors before claiming all lights changed. A lost response does not justify repeating relative brightness adjustments. See [authorization rules](/docs/for-ai/guides/authorization-rules.md).

package/generated/public/docs/for-ai/guides/using-the-api.md

@@ -1,9 +1,27 @@
 # Using the REST API
 
-Discover authorization metadata, then use [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Obtain exact REST paths and schemas from [OpenAPI](/docs/references/openapi.yaml) or [small operation pages](/docs/for-ai/operations/index.md).
+Discover authorization metadata, then use [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md).
+Start with the [compact API catalog](/docs/for-ai/api-catalog.md). It
+contains auth context, public operation links, parameter names and top-level JSON
+keys. Obtain exact REST paths from its links or the [small operation index](/docs/for-ai/operations/index.md).
+Follow one operation's linked schemas for required/conditional fields and
+nested payloads. It does not inline all schemas or examples.
+
+For SDK generation or a comprehensive contract download, request the
+[full OpenAPI document](/docs/references/openapi.yaml).
+
+The website's `/api/` route serves this compact Markdown when the request puts
+`text/markdown` first in `Accept` (for example,
+`text/markdown, text/plain;q=0.9, text/html;q=0.8`). Browser HTML requests keep the
+interactive reference. Add `?full=1` to explicitly retrieve the complete HTML
+catalog; keep HTML in your accepted formats for that request. Both variants
+include `Vary: Accept` for caches. The direct compact Markdown URL works on both
+the website and API host and does not depend on negotiation.
 
 Enumerate endpoints with endpoint:read. Follow returned pagination links/tokens exactly and stop only when continuation is absent. Inspect declared capabilities and versions; retrieve one message/attribute schema as needed. Send messages through POST /messages (the existing /messages/send alias also works). Never invent target IDs or message fields.
 
+For filtered inventory including readable shared endpoints, use [POST /endpoint-query](/docs/for-ai/operations/endpointQuery.md). Its query accepts exact match and nested and/or/not predicates; read the request schema's supported fields rather than inventing comparisons or text search. A groupId predicate additionally needs group:read and access to that group. Keep the query, page size, expansions, forceDeviceQuery setting and grant unchanged while following paginationContext.nextToken. Empty pages can have a continuation. Cursors expire after fifteen minutes; restart without nextToken on a 400 cursor error.
+
 REST dispatch and subsequent physical observation are separate facts. A 202 describes unfinished work. A timeout can mean the operation already acted; inspect existing results/state before repeating. IR/Bluetooth fire-and-forget and long-delay devices may never provide immediate confirmation. Use bounded polling and report unresolved state. An endpoint edit marked committed with cleanup pending must not be repeated as though it failed.
 
 Use documented idempotency/correlation and version preconditions only where the operation guarantees them. Setting a value and incrementing it have different replay risks. On an ambiguous lost relative-command response, report unknown or read back rather than blindly send again.

package/generated/public/docs/for-ai/index.md

@@ -13,6 +13,7 @@ Use [the shared connection guide](/docs/for-ai/guides/connect-agent.md) to selec
 ## Documentation tree: look up what you need
 
 - [Task/component guide directory](/docs/for-ai/guides/index.md): alternatives, not a required reading checklist
+- [Compact API catalog](/docs/for-ai/api-catalog.md): auth context and parameter/key index
 - [REST operation directory](/docs/for-ai/operations/index.md): individual operations and their scopes
 - [Small REST schema files](/docs/for-ai/schemas.md): linked request/response components
 - [Capability directory](/docs/for-ai/capability-interfaces.md): match the discovered namespace and version

package/generated/public/docs/for-ai/operations/endpointQuery.md

@@ -4,7 +4,7 @@ POST `/endpoint-query`
 
 
 
-Query for endpoints
+Return a bounded page of authorized endpoints matching the shared Query expression, including endpoints shared by other owners. Read permission is evaluated before filtering, pagination and state expansion. See the request schema for supported fields and operators. Use groupId to select members of a readable room/group, then intersect type or declared interfaces to select lights. Group predicates additionally require group:read for delegated OAuth. Repeat the complete query settings and grant when following nextToken; cursors expire after fifteen minutes. Device attributes are returned only when expanded. Report per-target command acceptance and observed state separately; querying a group does not grant permission to control its members.
 
 ## Authorization
 
@@ -19,6 +19,9 @@ security:
   - bearerAuth: []
 delegated: true
 resourcePermissionRequired: true
+conditionalScopes:
+  groupId:
+    - group:read
 ```
 
 ## Complete operation contract
@@ -29,7 +32,19 @@ post:
   operationId: endpointQuery
   tags:
     - Endpoints
-  description: Query for endpoints
+  description: >-
+    Return a bounded page of authorized endpoints matching the shared Query expression, including
+    endpoints shared by other owners. Read permission is evaluated before filtering, pagination and
+    state expansion. See the request schema for supported fields and operators. Use groupId to
+    select members of a readable room/group, then intersect type or declared interfaces to select
+    lights. Group predicates additionally require group:read for delegated OAuth. Repeat the
+    complete query settings and grant when following nextToken; cursors expire after fifteen
+    minutes. Device attributes are returned only when expanded. Report per-target command acceptance
+    and observed state separately; querying a group does not grant permission to control its
+    members.
+  x-portos-conditional-scopes:
+    groupId:
+      - group:read
   requestBody:
     required: true
     content:
@@ -39,8 +54,10 @@ post:
         example:
           query:
             match:
-              key: name
-              value: test
+              key: type
+              value: LIGHT
+          paginationContext:
+            maxResults: 10
   responses:
     '200':
       description: Endpoints retrieved successfully
@@ -50,10 +67,8 @@ post:
             $ref: /docs/references/schemas/EndpointQueryResponse.json
           example:
             results: []
-            paginationContext:
-              nextToken: abc123
     '400':
-      description: Bad request - missing required parameters
+      description: Invalid query, unsupported expansion, or invalid/expired/mismatched cursor.
       content:
         application/json:
           schema:
@@ -72,6 +87,36 @@ post:
             message: Unauthorized - invalid or missing authentication token
             code: UNAUTHORIZED
             family: AUTHENTICATION
+    '403':
+      description: Missing conditional OAuth scope or permission to read a referenced group.
+      content:
+        application/json:
+          schema:
+            $ref: /docs/references/schemas/Error.json
+          example:
+            message: Permission to read the requested group is required.
+            code: FORBIDDEN
+            family: FORBIDDEN
+    '404':
+      description: A referenced group does not exist.
+      content:
+        application/json:
+          schema:
+            $ref: /docs/references/schemas/Error.json
+          example:
+            message: Requested group was not found.
+            code: NOT_FOUND
+            family: NOT_FOUND
+    '409':
+      description: A selected disabled endpoint cannot be forcibly refreshed.
+      content:
+        application/json:
+          schema:
+            $ref: /docs/references/schemas/Error.json
+          example:
+            message: endpoint messaging is disabled
+            code: ENDPOINT_DISABLED
+            family: CONFLICT
     '500':
       description: Internal server error
       content:

package/generated/public/docs/for-ai/schemas/b-1.md

@@ -17,6 +17,7 @@
 - [BatteryInterfaceBatteryAttribute](/docs/references/schemas/BatteryInterfaceBatteryAttribute.json) (schemas)
 - [BatteryInterfaceConfiguration](/docs/references/schemas/BatteryInterfaceConfiguration.json) (schemas)
 - [BrandingInformation](/docs/references/schemas/BrandingInformation.json) (schemas)
+- [BrightnessInterfaceAdjustBrightnessMessage](/docs/references/schemas/BrightnessInterfaceAdjustBrightnessMessage.json) (schemas)
 - [BrightnessInterfaceBrightnessAttribute](/docs/references/schemas/BrightnessInterfaceBrightnessAttribute.json) (schemas)
 - [BrightnessInterfaceConfiguration](/docs/references/schemas/BrightnessInterfaceConfiguration.json) (schemas)
 - [BrightnessInterfaceSetBrightnessMessage](/docs/references/schemas/BrightnessInterfaceSetBrightnessMessage.json) (schemas)

package/generated/public/docs/for-ai/schemas/m-1.md

@@ -9,6 +9,7 @@
 - [MediaPlayerInterfaceAudioMessage](/docs/references/schemas/MediaPlayerInterfaceAudioMessage.json) (schemas)
 - [MediaPlayerInterfaceAudioStreamMessage](/docs/references/schemas/MediaPlayerInterfaceAudioStreamMessage.json) (schemas)
 - [MediaPlayerInterfaceConfiguration](/docs/references/schemas/MediaPlayerInterfaceConfiguration.json) (schemas)
+- [MediaPlayerInterfaceFastForwardMessage](/docs/references/schemas/MediaPlayerInterfaceFastForwardMessage.json) (schemas)
 - [MediaPlayerInterfaceNextMessage](/docs/references/schemas/MediaPlayerInterfaceNextMessage.json) (schemas)
 - [MediaPlayerInterfacePauseMessage](/docs/references/schemas/MediaPlayerInterfacePauseMessage.json) (schemas)
 - [MediaPlayerInterfacePlayAudioMessage](/docs/references/schemas/MediaPlayerInterfacePlayAudioMessage.json) (schemas)
@@ -32,6 +33,7 @@
 - [MediaPlaylistInterfacePlayPlaylistMessage](/docs/references/schemas/MediaPlaylistInterfacePlayPlaylistMessage.json) (schemas)
 - [MediaPlaylistInterfaceRemoveFromPlaylistMessage](/docs/references/schemas/MediaPlaylistInterfaceRemoveFromPlaylistMessage.json) (schemas)
 - [MediaPlaylistInterfaceShufflePlaylistMessage](/docs/references/schemas/MediaPlaylistInterfaceShufflePlaylistMessage.json) (schemas)
+- [MediaProvider](/docs/references/schemas/MediaProvider.json) (schemas)
 - [MediaSearchCapabilityInterfaceConfiguration](/docs/references/schemas/MediaSearchCapabilityInterfaceConfiguration.json) (schemas)
 - [MediaSearchInterfaceAudioMediaResultsMessage](/docs/references/schemas/MediaSearchInterfaceAudioMediaResultsMessage.json) (schemas)
 - [MediaSearchInterfaceSearchMediaMessage](/docs/references/schemas/MediaSearchInterfaceSearchMediaMessage.json) (schemas)
@@ -40,5 +42,3 @@
 - [MessageContext](/docs/references/schemas/MessageContext.json) (schemas)
 - [MessageEndpoint](/docs/references/schemas/MessageEndpoint.json) (schemas)
 - [MessageHeader](/docs/references/schemas/MessageHeader.json) (schemas)
-- [MessageInterfaceConfiguration](/docs/references/schemas/MessageInterfaceConfiguration.json) (schemas)
-- [MessageSourceNodeConfiguration](/docs/references/schemas/MessageSourceNodeConfiguration.json) (schemas)

package/generated/public/docs/for-ai/schemas/m-2.md

@@ -2,6 +2,8 @@
 
 [Schema directory](/docs/for-ai/schemas.md). Follow only the components linked by your operation.
 
+- [MessageInterfaceConfiguration](/docs/references/schemas/MessageInterfaceConfiguration.json) (schemas)
+- [MessageSourceNodeConfiguration](/docs/references/schemas/MessageSourceNodeConfiguration.json) (schemas)
 - [MessageTarget](/docs/references/schemas/MessageTarget.json) (schemas)
 - [MessageTargetGroupRoute](/docs/references/schemas/MessageTargetGroupRoute.json) (schemas)
 - [MessageTargetGroupRouteReference](/docs/references/schemas/MessageTargetGroupRouteReference.json) (schemas)

package/generated/public/docs/for-ai/schemas.md

@@ -6,7 +6,7 @@ Start with [the REST operation directory](/docs/for-ai/operations/index.md) and
 
 - [AccessControlEntity – AuthorizationInterfaceAuthorizationUpdateReportMessage](/docs/for-ai/schemas/a-1.md) (40 components)
 - [AuthorizationInterfaceConfiguration – AuthResourceType](/docs/for-ai/schemas/a-2.md) (5 components)
-- [BarrierControlInterfaceBarrierPositionAttribute – BrightnessInterfaceSetBrightnessMessage](/docs/for-ai/schemas/b-1.md) (18 components)
+- [BarrierControlInterfaceBarrierPositionAttribute – BrightnessInterfaceSetBrightnessMessage](/docs/for-ai/schemas/b-1.md) (19 components)
 - [CalendarEvent – ColorTemperatureInterfaceSetColorTemperatureMessage](/docs/for-ai/schemas/c-1.md) (40 components)
 - [ConductivityInterfaceMeasuredValueAttribute – CooktopInterfaceOperationalStateAttribute](/docs/for-ai/schemas/c-2.md) (40 components)
 - [CreateEndpointGroupItem – CustomPluginSecret](/docs/for-ai/schemas/c-3.md) (12 components)
@@ -20,8 +20,8 @@ Start with [the REST operation directory](/docs/for-ai/operations/index.md) and
 - [InferenceNodeConfiguration – IfMatch](/docs/for-ai/schemas/i-1.md) (9 components)
 - [KeypadInputInterfaceConfiguration – KeypadInputInterfaceSendKeyMessage](/docs/for-ai/schemas/k-1.md) (2 components)
 - [LaundryDryerInterfaceConfiguration – LockInterfaceUnlockMessage](/docs/for-ai/schemas/l-1.md) (18 components)
-- [MeasurementRange – MessageSourceNodeConfiguration](/docs/for-ai/schemas/m-1.md) (40 components)
-- [MessageTarget – MovementInstruction](/docs/for-ai/schemas/m-2.md) (12 components)
+- [MeasurementRange – MessageHeader](/docs/for-ai/schemas/m-1.md) (40 components)
+- [MessageInterfaceConfiguration – MovementInstruction](/docs/for-ai/schemas/m-2.md) (14 components)
 - [NO2ConcMeasInterfaceConfiguration – NotificationTimeWindow](/docs/for-ai/schemas/n-1.md) (11 components)
 - [O3ConcMeasInterfaceConfiguration – OvenInterfaceTemperatureAttribute](/docs/for-ai/schemas/o-1.md) (16 components)
 - [PaginationContext – PluginType](/docs/for-ai/schemas/p-1.md) (40 components)

package/generated/public/docs/references/authorization.json

@@ -160,7 +160,12 @@
         }
       ],
       "delegated": true,
-      "resourcePermissionRequired": true
+      "resourcePermissionRequired": true,
+      "conditionalScopes": {
+        "groupId": [
+          "group:read"
+        ]
+      }
     },
     {
       "path": "/events",

package/generated/public/docs/references/authorization.yaml

@@ -123,6 +123,9 @@ operations:
       - bearerAuth: []
     delegated: true
     resourcePermissionRequired: true
+    conditionalScopes:
+      groupId:
+        - group:read
   - path: /events
     runtimePath: /events
     method: POST

package/generated/public/docs/references/capability-interfaces/brightness/1.0/messages/adjust-brightness.yaml

@@ -0,0 +1,12 @@
+description: >-
+  Adjust brightness by a signed number of percentage points. The endpoint must
+  advertise this message separately from set-brightness.
+type: object
+properties:
+  brightnessDelta:
+    type: integer
+    minimum: -100
+    maximum: 100
+required:
+  - brightnessDelta
+additionalProperties: false

package/generated/public/docs/references/capability-interfaces/brightness/1.0.yaml

@@ -5,6 +5,24 @@ description: >-
   Brightness sets how bright a connected device should be and reports its current level. Use it to
   dim a light for the evening or restore a brighter setting for work.
 messages:
+  - name: adjust-brightness
+    description: >-
+      Adjust brightness by a signed number of percentage points. The endpoint must advertise this
+      message separately from set-brightness.
+    directionality: in
+    schema:
+      description: >-
+        Adjust brightness by a signed number of percentage points. The endpoint must advertise this
+        message separately from set-brightness.
+      type: object
+      properties:
+        brightnessDelta:
+          type: integer
+          minimum: -100
+          maximum: 100
+      required:
+        - brightnessDelta
+      additionalProperties: false
   - name: set-brightness
     description: null
     directionality: in

package/generated/public/docs/references/capability-interfaces/brightness.yaml

@@ -5,6 +5,24 @@ description: >-
   Brightness sets how bright a connected device should be and reports its current level. Use it to
   dim a light for the evening or restore a brighter setting for work.
 messages:
+  - name: adjust-brightness
+    description: >-
+      Adjust brightness by a signed number of percentage points. The endpoint must advertise this
+      message separately from set-brightness.
+    directionality: in
+    schema:
+      description: >-
+        Adjust brightness by a signed number of percentage points. The endpoint must advertise this
+        message separately from set-brightness.
+      type: object
+      properties:
+        brightnessDelta:
+          type: integer
+          minimum: -100
+          maximum: 100
+      required:
+        - brightnessDelta
+      additionalProperties: false
   - name: set-brightness
     description: null
     directionality: in

package/generated/public/docs/references/capability-interfaces/keypad-input/1.0/configuration.yaml

@@ -20,6 +20,7 @@ properties:
         - LEFT
         - RIGHT
         - SELECT
+        - HOME
         - BACK
         - EXIT
         - MENU

package/generated/public/docs/references/capability-interfaces/keypad-input/1.0/messages/send-key.yaml

@@ -18,6 +18,7 @@ properties:
       - LEFT
       - RIGHT
       - SELECT
+      - HOME
       - BACK
       - EXIT
       - MENU

package/generated/public/docs/references/capability-interfaces/keypad-input/1.0.yaml

@@ -29,6 +29,7 @@ messages:
             - LEFT
             - RIGHT
             - SELECT
+            - HOME
             - BACK
             - EXIT
             - MENU
@@ -82,6 +83,7 @@ configuration:
           - LEFT
           - RIGHT
           - SELECT
+          - HOME
           - BACK
           - EXIT
           - MENU

package/generated/public/docs/references/capability-interfaces/keypad-input.yaml

@@ -29,6 +29,7 @@ messages:
             - LEFT
             - RIGHT
             - SELECT
+            - HOME
             - BACK
             - EXIT
             - MENU
@@ -82,6 +83,7 @@ configuration:
           - LEFT
           - RIGHT
           - SELECT
+          - HOME
           - BACK
           - EXIT
           - MENU

package/generated/public/docs/references/capability-interfaces/media-player/1.0/configuration.yaml

@@ -3,6 +3,46 @@ description: >-
   playback. Read playback state and use only the commands supported by the connected player.
 type: object
 properties:
+  supportedAudioProviders:
+    type: array
+    uniqueItems: true
+    description: >-
+      Audio services accepted by search-and-play on this endpoint. These describe command support,
+      not active subscriptions.
+    items:
+      type: string
+      description: >-
+        Media service identifier. A provider enum value does not imply that every endpoint supports
+        that service; use the endpoint's advertised provider lists.
+      enum:
+        - SPOTIFY
+        - AMAZON_MUSIC
+        - APPLE_MUSIC
+        - AUDIBLE
+        - TUNE_IN
+        - PANDORA
+        - IHEART_RADIO
+        - SIRIUSXM
+        - DEEZER
+        - TIDAL
+        - YOUTUBE
+        - NETFLIX
+        - PRIME_VIDEO
+        - DAILYMOTION
+  supportedVideoProviders:
+    type: array
+    uniqueItems: true
+    description: >-
+      Video services accepted by search-and-play on this endpoint. These describe command support,
+      not installed applications or active subscriptions.
+    items:
+      $ref: '#/properties/supportedAudioProviders/items'
+  defaultAudioProvider:
+    $ref: '#/properties/supportedAudioProviders/items'
+    description: Default service for an audio search. Must be in supportedAudioProviders.
+  defaultVideoProvider:
+    $ref: '#/properties/supportedAudioProviders/items'
+    description: Default service for a video search. Must be in supportedVideoProviders.
   supportedPlaybackStates:
     type: array
     items:

package/generated/public/docs/references/capability-interfaces/media-player/1.0/messages/fast-forward.yaml

@@ -0,0 +1,5 @@
+description: >-
+  Begin provider-defined fast-forward playback. This does not seek by a specific
+  duration; use skip-forward or seek for a known position change.
+type: object
+additionalProperties: false