@portpowered/reference-data 0.4.5 → 0.4.6

package/generated/guides.json

@@ -50,7 +50,7 @@
   {
     "id": "lighting",
     "title": "Control lights and distinguish switches and plugs",
-    "content": "# Control lights and distinguish switches and plugs\n\nStart with authorized endpoint discovery and inspect capability declarations. A room name can be ambiguous; select by full ID and group path or ask the user. A power-capable plug or switch is not automatically a light.\n\nFor 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.\n\nFor “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.\n\nA 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).\n",
+    "content": "# Control lights and distinguish switches and plugs\n\nStart with authorized endpoint discovery and inspect capability declarations. A room name can be ambiguous; select by full ID and group path or ask the user. A power-capable plug or switch is not automatically a light.\n\nFor 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.\n\nFor “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.\n\n```json\n{\n  \"query\": {\n    \"or\": [\n      {\"match\": {\"key\": \"type\", \"value\": \"LIGHT\"}},\n      {\"match\": {\"key\": \"type\", \"value\": \"LIGHTBULB\"}}\n    ]\n  },\n  \"paginationContext\": {\"maxResults\": 25}\n}\n```\n\nFor 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.\n\nRepeat 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.\n\nA 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).\n",
     "setupPrompt": null
   },
   {
@@ -128,7 +128,7 @@
   {
     "id": "using-the-api",
     "title": "Using the REST API",
-    "content": "# Using the REST API\n\nDiscover 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).\n\nEnumerate 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.\n\nREST 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.\n\nUse 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.\n\nRead [authorization rules](/docs/for-ai/guides/authorization-rules.md), [lighting](/docs/for-ai/guides/lighting.md) or the relevant task guide.\n",
+    "content": "# Using the REST API\n\nDiscover authorization metadata, then use [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md).\nStart with the [compact API catalog](/docs/for-ai/api-catalog.md). It\ncontains auth context, public operation links, parameter names and top-level JSON\nkeys. Obtain exact REST paths from its links or the [small operation index](/docs/for-ai/operations/index.md).\nFollow one operation's linked schemas for required/conditional fields and\nnested payloads. It does not inline all schemas or examples.\n\nFor SDK generation or a comprehensive contract download, request the\n[full OpenAPI document](/docs/references/openapi.yaml).\n\nThe website's `/api/` route serves this compact Markdown when the request puts\n`text/markdown` first in `Accept` (for example,\n`text/markdown, text/plain;q=0.9, text/html;q=0.8`). Browser HTML requests keep the\ninteractive reference. Add `?full=1` to explicitly retrieve the complete HTML\ncatalog; keep HTML in your accepted formats for that request. Both variants\ninclude `Vary: Accept` for caches. The direct compact Markdown URL works on both\nthe website and API host and does not depend on negotiation.\n\nEnumerate 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.\n\nFor 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.\n\nREST 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.\n\nUse 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.\n\nRead [authorization rules](/docs/for-ai/guides/authorization-rules.md), [lighting](/docs/for-ai/guides/lighting.md) or the relevant task guide.\n",
     "setupPrompt": null
   },
   {

package/generated/openapi.json

@@ -1086,7 +1086,12 @@
         "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": {
@@ -1097,9 +1102,12 @@
               "example": {
                 "query": {
                   "match": {
-                    "key": "name",
-                    "value": "test"
+                    "key": "type",
+                    "value": "LIGHT"
                   }
+                },
+                "paginationContext": {
+                  "maxResults": 10
                 }
               }
             }
@@ -1114,16 +1122,13 @@
                   "$ref": "#/components/schemas/EndpointQueryResponse"
                 },
                 "example": {
-                  "results": [],
-                  "paginationContext": {
-                    "nextToken": "abc123"
-                  }
+                  "results": []
                 }
               }
             }
           },
           "400": {
-            "description": "Bad request - missing required parameters",
+            "description": "Invalid query, unsupported expansion, or invalid/expired/mismatched cursor.",
             "content": {
               "application/json": {
                 "schema": {
@@ -1152,6 +1157,51 @@
               }
             }
           },
+          "403": {
+            "description": "Missing conditional OAuth scope or permission to read a referenced group.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "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": "#/components/schemas/Error"
+                },
+                "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": "#/components/schemas/Error"
+                },
+                "example": {
+                  "message": "endpoint messaging is disabled",
+                  "code": "ENDPOINT_DISABLED",
+                  "family": "CONFLICT"
+                }
+              }
+            }
+          },
           "500": {
             "description": "Internal server error",
             "content": {
@@ -23657,22 +23707,50 @@
       },
       "EndpointQueryRequest": {
         "type": "object",
+        "additionalProperties": false,
         "required": [
           "query"
         ],
         "properties": {
           "query": {
-            "$ref": "#/components/schemas/Query"
+            "$ref": "#/components/schemas/Query",
+            "description": "A bounded shared Query expression. An empty object selects unfiltered readable inventory. This endpoint supports match, and, or, and not. Scalar match keys are id, name, type, ownerId, manufacturer, model, and enablement. interfaces matches membership in the endpoint's declared interface names; groupId matches membership in a readable endpoint group. Comparisons, patterns, freeform search, unknown keys, ambiguous nodes, expressions deeper than eight levels, or more than 64 nodes return 400. Values are exact strings. Collections hide disabled endpoints unless the expression explicitly filters enablement. Results include readable shared endpoints, regardless of their owner. A groupId predicate additionally requires group:read for delegated OAuth and read permission on that group."
           },
           "paginationContext": {
-            "$ref": "#/components/schemas/PaginationContext"
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "maxResults": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 10,
+                "description": "Maximum authorized matching endpoints in this page."
+              },
+              "nextToken": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Opaque server-issued continuation token. Repeat the same query, page size, expansions, forceDeviceQuery setting, and authenticated grant. Modified, expired, or differently bound tokens return 400; restart without nextToken. Follow nextToken until absent, including empty pages."
+              }
+            }
           },
           "expand": {
             "type": "array",
-            "description": "Expansion tokens that request related or computed endpoint fields.",
+            "uniqueItems": true,
+            "maxItems": 1,
+            "description": "Optional reported state expansion; only interfaces.attributes is supported.",
             "items": {
-              "type": "string"
+              "type": "string",
+              "enum": [
+                "interfaces.attributes"
+              ],
+              "x-enum-exempt": "Existing published REST expansion token shared with GET /endpoints."
             }
+          },
+          "forceDeviceQuery": {
+            "type": "boolean",
+            "default": false,
+            "description": "Refresh reported device attributes for the selected page. Requires expand to contain interfaces.attributes. An accepted command is not proof of device state; inspect the returned sample times and partial errors. Disabled endpoints cannot be forcibly refreshed."
           }
         }
       },

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/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/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/manifest.json

@@ -1,13 +1,137 @@
 {
   "package": "@portpowered/reference-data",
   "goModule": "github.com/portpowered/portos-reference-data",
-  "version": "0.4.5",
-  "sourceCommit": "07fdcc4ef4f322950ecb617ffaf47a79b9f0a122",
+  "version": "0.4.6",
+  "sourceCommit": "1a7e380ef931f684ad0c4dfb9e3d73b20a01bd69",
   "sourceInputState": "committed",
-  "sourceInputSHA256": "d8183268527e9f3de34ec8374b1007a4ed48cc0d4255dd8c3bc5822f10e57818",
+  "sourceInputSHA256": "373c0f48bd6955157efd5047090454fbd7efa42313debb76229b413567102c22",
   "sourceInputCount": 735,
-  "assetSetSHA256": "bae4942d5ad905c28c49cd3967c8e3c24f54db3dc36c90119208fd9c12ef1adc",
+  "assetSetSHA256": "c0d41f747be314cd29b19dd70b1a380818fc431b44e91cfb3bea90ebeed55efb",
   "files": [
+    {
+      "path": "/docs/for-ai/api-catalog.md",
+      "contentType": "text/plain; charset=utf-8",
+      "bytes": 21280,
+      "sha256": "d0ed50538f4f1ce2f7ec9d4eb17bb3d713a24252ae8af2fbf91bf447e233462d",
+      "links": [
+        "/docs/for-ai/capability-interfaces.md",
+        "/docs/for-ai/guides/authentication-and-dcr.md",
+        "/docs/for-ai/guides/authorization-rules.md",
+        "/docs/for-ai/guides/quickstart.md",
+        "/docs/for-ai/operations/addEndpointGroupMembers.md",
+        "/docs/for-ai/operations/authorizeDevice.md",
+        "/docs/for-ai/operations/beginOAuthAuthorization.md",
+        "/docs/for-ai/operations/completeOAuthConsent.md",
+        "/docs/for-ai/operations/createEndpointGroup.md",
+        "/docs/for-ai/operations/createFlowNode.md",
+        "/docs/for-ai/operations/createFlowRun.md",
+        "/docs/for-ai/operations/createOAuthClient.md",
+        "/docs/for-ai/operations/createSyntheticEvent.md",
+        "/docs/for-ai/operations/createToken.md",
+        "/docs/for-ai/operations/createView.md",
+        "/docs/for-ai/operations/deleteAccessControlRule.md",
+        "/docs/for-ai/operations/deleteAuthLink.md",
+        "/docs/for-ai/operations/deleteEndpoint.md",
+        "/docs/for-ai/operations/deleteEndpointGroup.md",
+        "/docs/for-ai/operations/deleteEventDeadLetter.md",
+        "/docs/for-ai/operations/deleteFlow.md",
+        "/docs/for-ai/operations/deleteFlowNode.md",
+        "/docs/for-ai/operations/deleteFlowRun.md",
+        "/docs/for-ai/operations/deleteGroupRoute.md",
+        "/docs/for-ai/operations/deleteOAuthClient.md",
+        "/docs/for-ai/operations/deletePlugin.md",
+        "/docs/for-ai/operations/deletePrincipal.md",
+        "/docs/for-ai/operations/deleteRoute.md",
+        "/docs/for-ai/operations/deleteSecret.md",
+        "/docs/for-ai/operations/deleteSimulator.md",
+        "/docs/for-ai/operations/deleteSubscription.md",
+        "/docs/for-ai/operations/deleteView.md",
+        "/docs/for-ai/operations/deviceAuthorize.md",
+        "/docs/for-ai/operations/endpointGroupsManage.md",
+        "/docs/for-ai/operations/endpointQuery.md",
+        "/docs/for-ai/operations/enumerateAuthLinks.md",
+        "/docs/for-ai/operations/enumerateEndpointGroups.md",
+        "/docs/for-ai/operations/enumerateEndpoints.md",
+        "/docs/for-ai/operations/enumerateEventDeadLetters.md",
+        "/docs/for-ai/operations/enumerateFlowNodeSpecifications.md",
+        "/docs/for-ai/operations/enumerateFlowNodes.md",
+        "/docs/for-ai/operations/enumerateGroupRelationships.md",
+        "/docs/for-ai/operations/enumerateGroupRoutes.md",
+        "/docs/for-ai/operations/enumerateOAuthClients.md",
+        "/docs/for-ai/operations/enumeratePlugins.md",
+        "/docs/for-ai/operations/enumeratePrincipals.md",
+        "/docs/for-ai/operations/enumerateSecrets.md",
+        "/docs/for-ai/operations/enumerateSimulators.md",
+        "/docs/for-ai/operations/enumerateSubscriptions.md",
+        "/docs/for-ai/operations/enumerateTokens.md",
+        "/docs/for-ai/operations/enumerateViews.md",
+        "/docs/for-ai/operations/establishAuthLink.md",
+        "/docs/for-ai/operations/establishPlugin.md",
+        "/docs/for-ai/operations/evaluateAccessControlRule.md",
+        "/docs/for-ai/operations/generateOAuthCode.md",
+        "/docs/for-ai/operations/generateToken.md",
+        "/docs/for-ai/operations/generateTuyaQrCode.md",
+        "/docs/for-ai/operations/getAccessControlRules.md",
+        "/docs/for-ai/operations/getEndpointGroup.md",
+        "/docs/for-ai/operations/getEventDeadLetter.md",
+        "/docs/for-ai/operations/getEventReceipt.md",
+        "/docs/for-ai/operations/getJWKS.md",
+        "/docs/for-ai/operations/getMCPOAuthProtectedResourceMetadata.md",
+        "/docs/for-ai/operations/getMetrics.md",
+        "/docs/for-ai/operations/getOAuthAuthorizationServerMetadata.md",
+        "/docs/for-ai/operations/getOAuthClient.md",
+        "/docs/for-ai/operations/getOAuthProtectedResourceMetadata.md",
+        "/docs/for-ai/operations/getOpenIDConfiguration.md",
+        "/docs/for-ai/operations/getPendingOAuthConsent.md",
+        "/docs/for-ai/operations/getRoutes.md",
+        "/docs/for-ai/operations/getSubscription.md",
+        "/docs/for-ai/operations/getView.md",
+        "/docs/for-ai/operations/handleGitHubWebhook.md",
+        "/docs/for-ai/operations/handleGoogleCloudSchedulerWebhook.md",
+        "/docs/for-ai/operations/handleOAuthCallback.md",
+        "/docs/for-ai/operations/handleSmartThingsWebhook.md",
+        "/docs/for-ai/operations/invalidateToken.md",
+        "/docs/for-ai/operations/modifyEndpoint.md",
+        "/docs/for-ai/operations/patchSubscription.md",
+        "/docs/for-ai/operations/ping.md",
+        "/docs/for-ai/operations/pluginAuthCodeExchange.md",
+        "/docs/for-ai/operations/pluginAuthCodeLink.md",
+        "/docs/for-ai/operations/pluginAuthMultifactorExchange.md",
+        "/docs/for-ai/operations/pushToMessageGateway.md",
+        "/docs/for-ai/operations/queryFlowRuns.md",
+        "/docs/for-ai/operations/queryFlows.md",
+        "/docs/for-ai/operations/raiseAnonymousPrincipal.md",
+        "/docs/for-ai/operations/redriveEventDeadLetter.md",
+        "/docs/for-ai/operations/refreshAuthLinkToken.md",
+        "/docs/for-ai/operations/registerDynamicOAuthClient.md",
+        "/docs/for-ai/operations/removeEndpointGroupMembers.md",
+        "/docs/for-ai/operations/requestFutureIntegration.md",
+        "/docs/for-ai/operations/revokeOAuthGrant.md",
+        "/docs/for-ai/operations/sendMessage.md",
+        "/docs/for-ai/operations/sendMessageLegacyAlias.md",
+        "/docs/for-ai/operations/setEndpointGroupName.md",
+        "/docs/for-ai/operations/setFlowRunStatus.md",
+        "/docs/for-ai/operations/synchronizeRoutes.md",
+        "/docs/for-ai/operations/triggerFlow.md",
+        "/docs/for-ai/operations/updateOAuthClient.md",
+        "/docs/for-ai/operations/updateView.md",
+        "/docs/for-ai/operations/upsertAccessControlRule.md",
+        "/docs/for-ai/operations/upsertAuthLink.md",
+        "/docs/for-ai/operations/upsertEndpoint.md",
+        "/docs/for-ai/operations/upsertFlow.md",
+        "/docs/for-ai/operations/upsertFlowRunMessage.md",
+        "/docs/for-ai/operations/upsertPluginRequest.md",
+        "/docs/for-ai/operations/upsertPrincipal.md",
+        "/docs/for-ai/operations/upsertRoute.md",
+        "/docs/for-ai/operations/upsertSecret.md",
+        "/docs/for-ai/operations/upsertSimulator.md",
+        "/docs/for-ai/operations/upsertSubscription.md",
+        "/docs/for-ai/operations/validateOAuthRequest.md",
+        "/docs/for-ai/operations/validateTuyaLoginCode.md",
+        "/docs/for-ai/operations/verifyDevice.md",
+        "/docs/references/openapi.yaml"
+      ]
+    },
     {
       "path": "/docs/for-ai/capability-interfaces.md",
       "contentType": "text/plain; charset=utf-8",
@@ -1303,12 +1427,14 @@
     {
       "path": "/docs/for-ai/guides/lighting.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 1290,
-      "sha256": "f393b36c9e149709185f18d4b7f2c29a6fae457d18c2d32e34c56040efb1fb3f",
+      "bytes": 2462,
+      "sha256": "4630b0541a7b9de1c605d4bbf9dee7946a0889ca0eb364c628a9878f868e27fe",
       "links": [
         "/docs/for-ai/capability-interfaces.md",
         "/docs/for-ai/guides/authorization-rules.md",
-        "/docs/for-ai/guides/quickstart.md"
+        "/docs/for-ai/guides/managing-groups.md",
+        "/docs/for-ai/guides/quickstart.md",
+        "/docs/for-ai/operations/endpointQuery.md"
       ]
     },
     {
@@ -1454,12 +1580,14 @@
     {
       "path": "/docs/for-ai/guides/using-the-api.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 1490,
-      "sha256": "3d54f9aadddb70cfe6630f8a72cbf50f0163467768e09fc5beece88b8538e909",
+      "bytes": 2995,
+      "sha256": "13207d4668ca60055c5edc4ab4b9f582abdb5a676c9edaacc5c92c054672819d",
       "links": [
+        "/docs/for-ai/api-catalog.md",
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/guides/authorization-rules.md",
         "/docs/for-ai/guides/lighting.md",
+        "/docs/for-ai/operations/endpointQuery.md",
         "/docs/for-ai/operations/index.md",
         "/docs/references/openapi.yaml"
       ]
@@ -1477,9 +1605,10 @@
     {
       "path": "/docs/for-ai/index.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 1973,
-      "sha256": "303ac8481dfd46c092f1e9fe988740878d146d0194404b309eeb554f4eb2973c",
+      "bytes": 2064,
+      "sha256": "a34ccabe7c6f4b0b9d1b35eece14fdebbdf6ec638596232a8528d4d4714a9fa1",
       "links": [
+        "/docs/for-ai/api-catalog.md",
         "/docs/for-ai/capability-interfaces.md",
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/guides/connect-agent.md",
@@ -1844,8 +1973,8 @@
     {
       "path": "/docs/for-ai/operations/endpointQuery.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 2554,
-      "sha256": "aac7b487054a992fa385bef6e8df068e79789a9c8d12e08678aa196f8c76af2f",
+      "bytes": 5199,
+      "sha256": "85bf525fe235fafa09159bb4437fcb543a4de8c99dcec57077601b3e7af958a2",
       "links": [
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/schemas.md",
@@ -3980,15 +4109,15 @@
     {
       "path": "/docs/references/authorization.json",
       "contentType": "application/json",
-      "bytes": 38378,
-      "sha256": "459c04391581ab68829ab3db1b89a99ec1bee41948afee6c314702a27d054370",
+      "bytes": 38470,
+      "sha256": "d989ea6620017866d148d85cea1b23754c66132e2a91d0263d17a315b3e7066e",
       "links": []
     },
     {
       "path": "/docs/references/authorization.yaml",
       "contentType": "application/yaml; charset=utf-8",
-      "bytes": 28365,
-      "sha256": "00ceec4850728a5e80577a592c132d3a881686b407c3fd2784b4fba1eaf8f57f",
+      "bytes": 28424,
+      "sha256": "49456bdf5aabc3dfcee05bb1dece7fe89e0d727eecc58bac510943d736a7345e",
       "links": []
     },
     {
@@ -7352,8 +7481,8 @@
     {
       "path": "/docs/references/openapi.yaml",
       "contentType": "application/yaml; charset=utf-8",
-      "bytes": 757609,
-      "sha256": "a6db7cfd7943b4298c07af9dbf1078bcccc15725fa3a4e7a329f92c18e19c89c",
+      "bytes": 761899,
+      "sha256": "a5ae633442765553a3fc97f5a14678290d8dee6d6458cd8975236659ef5537c8",
       "links": []
     },
     {
@@ -8759,8 +8888,8 @@
     {
       "path": "/docs/references/schemas/EndpointQueryRequest.json",
       "contentType": "application/json",
-      "bytes": 493,
-      "sha256": "7f3bc6e0aeca233394416f5edbf910f2caef13ab0817ecefc5a22dffaaf81239",
+      "bytes": 2558,
+      "sha256": "ace0583c690fcdce12a099f8d633322922dd51c428fc310e9dd33e0789a46074",
       "links": []
     },
     {

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

@@ -858,7 +858,19 @@ paths:
       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:
@@ -868,8 +880,10 @@ paths:
             example:
               query:
                 match:
-                  key: name
-                  value: test
+                  key: type
+                  value: LIGHT
+              paginationContext:
+                maxResults: 10
       responses:
         '200':
           description: Endpoints retrieved successfully
@@ -879,10 +893,8 @@ paths:
                 $ref: '#/components/schemas/EndpointQueryResponse'
               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:
@@ -901,6 +913,36 @@ paths:
                 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: '#/components/schemas/Error'
+              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: '#/components/schemas/Error'
+              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: '#/components/schemas/Error'
+              example:
+                message: endpoint messaging is disabled
+                code: ENDPOINT_DISABLED
+                family: CONFLICT
         '500':
           description: Internal server error
           content:
@@ -18543,18 +18585,59 @@ components:
           description: The value to match on
     EndpointQueryRequest:
       type: object
+      additionalProperties: false
       required:
         - query
       properties:
         query:
           $ref: '#/components/schemas/Query'
+          description: >-
+            A bounded shared Query expression. An empty object selects unfiltered readable
+            inventory. This endpoint supports match, and, or, and not. Scalar match keys are id,
+            name, type, ownerId, manufacturer, model, and enablement. interfaces matches membership
+            in the endpoint's declared interface names; groupId matches membership in a readable
+            endpoint group. Comparisons, patterns, freeform search, unknown keys, ambiguous nodes,
+            expressions deeper than eight levels, or more than 64 nodes return 400. Values are exact
+            strings. Collections hide disabled endpoints unless the expression explicitly filters
+            enablement. Results include readable shared endpoints, regardless of their owner. A
+            groupId predicate additionally requires group:read for delegated OAuth and read
+            permission on that group.
         paginationContext:
-          $ref: '#/components/schemas/PaginationContext'
+          type: object
+          additionalProperties: false
+          properties:
+            maxResults:
+              type: integer
+              minimum: 1
+              maximum: 100
+              default: 10
+              description: Maximum authorized matching endpoints in this page.
+            nextToken:
+              type: string
+              minLength: 1
+              description: >-
+                Opaque server-issued continuation token. Repeat the same query, page size,
+                expansions, forceDeviceQuery setting, and authenticated grant. Modified, expired, or
+                differently bound tokens return 400; restart without nextToken. Follow nextToken
+                until absent, including empty pages.
         expand:
           type: array
-          description: Expansion tokens that request related or computed endpoint fields.
+          uniqueItems: true
+          maxItems: 1
+          description: Optional reported state expansion; only interfaces.attributes is supported.
           items:
             type: string
+            enum:
+              - interfaces.attributes
+            x-enum-exempt: Existing published REST expansion token shared with GET /endpoints.
+        forceDeviceQuery:
+          type: boolean
+          default: false
+          description: >-
+            Refresh reported device attributes for the selected page. Requires expand to contain
+            interfaces.attributes. An accepted command is not proof of device state; inspect the
+            returned sample times and partial errors. Disabled endpoints cannot be forcibly
+            refreshed.
     Simulator:
       description: Legacy string-name application/json projection; default representation remains unchanged.
       allOf:

package/generated/public/docs/references/schemas/EndpointQueryRequest.json

@@ -1,22 +1,50 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
+  "additionalProperties": false,
   "required": [
     "query"
   ],
   "properties": {
     "query": {
-      "$ref": "/docs/references/schemas/Query.json"
+      "$ref": "/docs/references/schemas/Query.json",
+      "description": "A bounded shared Query expression. An empty object selects unfiltered readable inventory. This endpoint supports match, and, or, and not. Scalar match keys are id, name, type, ownerId, manufacturer, model, and enablement. interfaces matches membership in the endpoint's declared interface names; groupId matches membership in a readable endpoint group. Comparisons, patterns, freeform search, unknown keys, ambiguous nodes, expressions deeper than eight levels, or more than 64 nodes return 400. Values are exact strings. Collections hide disabled endpoints unless the expression explicitly filters enablement. Results include readable shared endpoints, regardless of their owner. A groupId predicate additionally requires group:read for delegated OAuth and read permission on that group."
     },
     "paginationContext": {
-      "$ref": "/docs/references/schemas/PaginationContext.json"
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxResults": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 10,
+          "description": "Maximum authorized matching endpoints in this page."
+        },
+        "nextToken": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Opaque server-issued continuation token. Repeat the same query, page size, expansions, forceDeviceQuery setting, and authenticated grant. Modified, expired, or differently bound tokens return 400; restart without nextToken. Follow nextToken until absent, including empty pages."
+        }
+      }
     },
     "expand": {
       "type": "array",
-      "description": "Expansion tokens that request related or computed endpoint fields.",
+      "uniqueItems": true,
+      "maxItems": 1,
+      "description": "Optional reported state expansion; only interfaces.attributes is supported.",
       "items": {
-        "type": "string"
+        "type": "string",
+        "enum": [
+          "interfaces.attributes"
+        ],
+        "x-enum-exempt": "Existing published REST expansion token shared with GET /endpoints."
       }
+    },
+    "forceDeviceQuery": {
+      "type": "boolean",
+      "default": false,
+      "description": "Refresh reported device attributes for the selected page. Requires expand to contain interfaces.attributes. An accepted command is not proof of device state; inspect the returned sample times and partial errors. Disabled endpoints cannot be forcibly refreshed."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portpowered/reference-data",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "private": false,
   "publishConfig": { "access": "public" },
   "repository": { "type": "git", "url": "https://github.com/portpowered/portos-reference-data.git" },