@portpowered/reference-data 0.4.1 → 0.4.3

package/generated/public/docs/for-ai/guides/authentication-and-dcr.md

@@ -2,7 +2,7 @@
 
 All supported agents use the same OAuth components. REST and MCP select different protected resources; DCR and CIMD select different registration methods. Neither product branding nor registration grants device access.
 
-Start with [Connect any supported agent](/docs/for-ai/guides/connect-agent.md), or follow these components in order:
+The complete walkthrough below is generated from the canonical components linked here. Read it in one document, or reference the individual components from your connector:
 
 1. [Discover endpoints and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).
 2. [Register with DCR or supported CIMD](/docs/for-ai/guides/oauth-client-registration.md). Remote callbacks require HTTPS; local callback registrations contain only localhost/loopback callbacks. Repeated canonical fingerprints reuse the original public client without expanding scopes.
@@ -11,3 +11,172 @@ Start with [Connect any supported agent](/docs/for-ai/guides/connect-agent.md),
 5. [Verify the connection](/docs/for-ai/guides/first-setup.md), then use [the REST quickstart](/docs/for-ai/guides/quickstart.md) or your client's MCP tools.
 
 Read [authorization rules](/docs/for-ai/guides/authorization-rules.md) for scopes, principal/resource policies, sharing and denial diagnosis. Never ask for a Google password, paste credentials into chat, or approve the agent's own grant. Claimed client names such as Muse and Grok remain unverified.
+
+## Discover the OAuth server and choose REST or MCP
+
+This discovery step is shared by every client. The deployed pilot API is https://api.portoperatingsystem.lol. Fetch its /.well-known/oauth-authorization-server document anonymously. Read issuer, authorization_endpoint, token_endpoint, registration_endpoint, revocation_endpoint and scopes_supported. Use the returned endpoints exactly. An alias can advertise a different canonical Cloud Run issuer; do not substitute the alias into token audiences.
+
+| Interface | API destination | OAuth resource |
+| --- | --- | --- |
+| REST | The returned issuer, plus the documented operation path | The exact returned issuer |
+| MCP | The returned issuer plus /mcp, Streamable HTTP | The resource returned by /.well-known/oauth-protected-resource/mcp, normally issuer plus /mcp |
+
+An MCP connector can start at https://api.portoperatingsystem.lol/mcp and follow its WWW-Authenticate resource_metadata URL. Fetch that public metadata and the authorization server it names. MCP initialization alone does not prove that the account's devices are accessible. Never use a REST token on MCP or an MCP token on REST.
+
+Choose one supported [client registration method](/docs/for-ai/guides/oauth-client-registration.md), then follow the same [consent and callback steps](/docs/for-ai/guides/oauth-consent-and-callback.md). If metadata omits registration_endpoint, new DCR registration is unavailable; do not guess a replacement endpoint or silently switch to another client's credentials.
+
+See [scopes and resource rules](/docs/for-ai/guides/authorization-rules.md). Authorization-server scopes_supported describes server vocabulary; a particular client's accepted scopes can be narrower.
+
+### Carry discovery values into every request
+
+This JavaScript fragment initializes a REST connection. Keep `authorizationServer` and `resource` for the consent and token examples; the API alias is only the discovery starting point.
+
+```javascript
+const response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');
+if (!response.ok) throw new Error('OAuth discovery failed');
+const authorizationServer = await response.json();
+const resource = authorizationServer.issuer;
+const apiBase = authorizationServer.issuer;
+```
+
+For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_request` error callback even when client registration succeeded.
+
+Canonical component: [Discover the OAuth server and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).
+
+## Register an OAuth client with DCR or CIMD
+
+Start with [discovery](/docs/for-ai/guides/oauth-discovery.md). DCR and CIMD identify a client; they do not sign in a user or grant device access. Both use the same [PKCE consent and callback flow](/docs/for-ai/guides/oauth-consent-and-callback.md) and [token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+
+### DCR: public clients
+
+POST application/json to the discovered registration_endpoint:
+
+```json
+{"client_name":"My device assistant","redirect_uris":["https://your-client.example/oauth/callback"],"token_endpoint_auth_method":"none","grant_types":["authorization_code","refresh_token"],"response_types":["code"],"scope":"endpoint:read message:send"}
+```
+
+Use a callback the client controls. Remote callbacks require HTTPS. Local clients may use exact HTTP callbacks on localhost or literal loopback IPs, such as http://127.0.0.1:8765/callback. All callbacks in a registration must be local or all must be remote; these sets cannot be mixed. No fragments or user information are permitted. Start the local callback listener before authorization. The website's client-management interface enforces this same callback-set policy.
+
+Success is 201 with client_id, client_id_issued_at and accepted metadata. Public clients get no client_secret. Supported DCR scopes are endpoint:read, endpoint:write, message:read, message:send, group:read, group:manage, subscription:read and subscription:write. The default is endpoint:read. Request only the task's necessary scopes and check the returned scope. Broader static-client scopes are outside this anonymous profile.
+
+The registration fingerprint is SHA-256 of compact canonical JSON with sorted object keys and sorted redirect_uris, grant_types and response_types arrays, plus client_name and token_endpoint_auth_method. Defaults are applied before hashing. Array ordering does not create another client. A matching registration returns the original client ID, issue time, scopes and descriptive metadata. It never overwrites the existing client or expands scopes, even if scope or software_id differs in the new request. Fingerprinting is deduplication, not proof of callback ownership or vendor identity.
+
+Default quotas are 1,000 new registrations per rolling day and 10,000 retained registrations. Reuse does not consume new-registration quota. A quota failure returns 429 with Retry-After. An operator can disable new registrations without retiring existing grants. Read the [registration operation](/docs/for-ai/operations/registerDynamicOAuthClient.md) for exact request, response and error schemas.
+
+### CIMD: allowlisted metadata clients
+
+A supported CIMD client uses its allowlisted HTTPS metadata URL as client_id instead of posting a DCR request. Port OS retrieves and validates that client metadata, including its exact callbacks and public PKCE profile. Arbitrary metadata URLs and redirects from the metadata fetch are not supported. If your metadata URL is not allowlisted, arrange onboarding or use DCR if your client supports it. Do not pretend another client's metadata URL belongs to you.
+
+Client_name, software_id, software_version and client_uri remain unverified claims. No trusted software-statement issuer is configured; software_statement is rejected. A registration called Muse or Grok does not establish a verified vendor integration or gain additional permissions. Static confidential clients retain their separately configured client authentication method.
+
+Canonical component: [Register an OAuth client with DCR or CIMD](/docs/for-ai/guides/oauth-client-registration.md).
+
+## Obtain user consent and validate the OAuth callback
+
+Use the endpoints and resource from [discovery](/docs/for-ai/guides/oauth-discovery.md) and the client ID and exact callback from [registration](/docs/for-ai/guides/oauth-client-registration.md). These steps are identical for DCR and CIMD, REST and MCP; the chosen resource is the transport-specific input.
+
+1. Start the callback handler the client controls. For a loopback callback, bind its listener locally before opening authorization.
+2. Generate a cryptographically random PKCE verifier of 43–128 permitted characters. Compute code_challenge = BASE64URL(SHA256(verifier)), without padding. Generate a separate random state and retain both in this authorization attempt.
+3. Open the discovered authorization_endpoint with the following query parameters. Percent-encode parameter values; do not append raw callback URLs or scopes into an unescaped query.
+
+```text
+client_id=<registered ID or supported CIMD metadata URL>
+redirect_uri=<exact registered callback>
+response_type=code
+scope=<requested subset of the client's accepted scopes>
+resource=<chosen canonical REST or MCP resource>
+state=<random client state>
+code_challenge=<S256 challenge>
+code_challenge_method=S256
+```
+
+For REST, use the `resource = authorizationServer.issuer` value retained from discovery. Construct the URL rather than writing an alias into a template. This JavaScript fragment assumes `clientId`, `redirectUri` and `acceptedScope` come from your registration response and callback configuration:
+
+```javascript
+const base64url = bytes => btoa(String.fromCharCode(...bytes))
+  .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
+const challenge = base64url(new Uint8Array(await crypto.subtle.digest(
+  'SHA-256', new TextEncoder().encode(verifier))));
+const authorizationURL = new URL(authorizationServer.authorization_endpoint);
+authorizationURL.search = new URLSearchParams({
+  client_id: clientId, redirect_uri: redirectUri, response_type: 'code',
+  scope: acceptedScope, resource, state,
+  code_challenge: challenge, code_challenge_method: 'S256',
+}).toString();
+// Retain verifier, state and authorizationServer.issuer privately until callback validation.
+// Open authorizationURL.href in the user's browser; wait for their consent.
+```
+
+The user signs in on Port OS and reviews the requested permissions. Pause for the user; an agent must not approve its own grant, request passwords or manufacture a production sign-in identity. Local functional tests substitute an existing signed fixture identity at this boundary without changing production sign-in.
+
+After approval, Port OS navigates to the exact callback with code, state and iss. Reject a callback whose state or issuer does not match this attempt. Treat an error callback as a denied or failed authorization, not a code. Codes and pending consent expire after ten minutes and are single-use. Do not paste codes or credentials into shared chat or logs. Continue with [code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).
+
+Canonical component: [Obtain user consent and validate the OAuth callback](/docs/for-ai/guides/oauth-consent-and-callback.md).
+
+## Exchange, refresh and revoke scoped OAuth tokens
+
+Complete [callback validation](/docs/for-ai/guides/oauth-consent-and-callback.md) first. For a public DCR/CIMD client, POST application/x-www-form-urlencoded to the discovered token_endpoint with:
+
+```text
+grant_type=authorization_code
+client_id=<client ID used for authorization>
+code=<validated callback code>
+redirect_uri=<the same exact callback>
+code_verifier=<this attempt's original verifier>
+resource=<the same canonical resource used for authorization>
+```
+
+Continue with the same discovery values and verifier from the consent example. `code` below must be from a callback whose `state` and `iss` you validated; abort on any callback `error`:
+
+```javascript
+const tokenResponse = await fetch(authorizationServer.token_endpoint, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: new URLSearchParams({
+    grant_type: 'authorization_code', client_id: clientId, code,
+    redirect_uri: redirectUri, code_verifier: verifier, resource,
+  }),
+});
+if (!tokenResponse.ok) throw new Error('OAuth code exchange failed');
+const tokens = await tokenResponse.json(); // Store securely; do not print tokens.
+```
+
+Save access_token, refresh_token and returned scope in the connector's secure credential store. Public clients have no client secret. Use Authorization: Bearer <access_token> with REST requests or the MCP HTTP connection, according to that token's resource. A refresh token is never an API credential. [Scopes bound access; resource policies still apply](/docs/for-ai/guides/authorization-rules.md).
+
+Refresh with grant_type=refresh_token, client_id, refresh_token and the original resource at token_endpoint. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.
+
+Revoke by POSTing application/x-www-form-urlencoded token=<refresh_token>&client_id=<client_id> to revocation_endpoint. Revoked grants stop authorizing both access and refresh requests. Removing a local configuration file alone is not server-side revocation.
+
+Read [the token operation](/docs/for-ai/operations/generateToken.md), [revocation operation](/docs/for-ai/operations/revokeOAuthGrant.md), and [connection recovery](/docs/for-ai/guides/troubleshooting.md) for schemas and failures. Verify account access using [first setup](/docs/for-ai/guides/first-setup.md), then perform only the customer's intended task. Dispatch acceptance is distinct from observed device state.
+
+Canonical component: [Exchange, refresh and revoke scoped OAuth tokens](/docs/for-ai/guides/oauth-token-lifecycle.md).
+
+## Scopes and authorization rules
+
+Authentication establishes the principal and client. OAuth scopes bound the user's delegated authority; resource rules decide which selected resources and actions that principal may access. A scope is not an ownership or sharing grant.
+
+For delegated REST grants, Port OS verifies token signature, expiry, issuer, REST audience, access-token type and active grant, then checks the operation's scope before existing service resource-policy evaluation. MCP tokens have a separate /mcp audience and cannot be reused on REST. A refresh token is never an API bearer credential.
+
+| Task | Scope |
+| --- | --- |
+| Enumerate or query endpoints/routes | endpoint:read |
+| Modify endpoints/routes | endpoint:write |
+| Send a device message | message:send |
+| Read groups and relationships | group:read |
+| Manage group membership | group:manage |
+| Read subscriptions | subscription:read |
+| Create/update/delete subscriptions | subscription:write |
+
+Other operations are outside the anonymous DCR device profile and fail closed. [Operation pages](/docs/for-ai/operations/index.md) expose exact credential alternatives and resource requirements. [Machine-readable authorization metadata](/docs/references/authorization.yaml) links the contract.
+
+The existing resource engine converts principal, action, resource and entity data into Cedar requests. Default owner rules and applicable sharing/conditional rules are evaluated; only an Allow outcome admits access. The typed operation IDs come from Port OS's policy action catalog, not invented dotted action names. Owning an endpoint does not override a delegated token's missing scope.
+
+A token with endpoint:read can enumerate permitted lights but cannot dispatch a command. Adding message:send permits dispatch only to endpoints that the signed-in principal's rules allow. An authorized light does not imply camera access. A generic power-capable plug is not automatically a light. For a group request, evaluate the selected targets and report denied or unresolved members separately.
+
+An invalid/expired/revoked token needs renewed authentication. A scope denial requires the user to approve the needed scope. A resource denial requires the owner to grant the appropriate resource/action access. Never fix denial by switching principal, requesting unrestricted credentials or retrying blindly. Provider authentication failures can require account relinking; they are different from Port OS policy denial. Keep inaccessible resource identities out of diagnostics.
+
+See [troubleshooting](/docs/for-ai/guides/troubleshooting.md).
+
+Canonical component: [Scopes and authorization rules](/docs/for-ai/guides/authorization-rules.md).

package/generated/public/docs/for-ai/guides/oauth-consent-and-callback.md

@@ -17,6 +17,25 @@ code_challenge=<S256 challenge>
 code_challenge_method=S256
 ```
 
+For REST, use the `resource = authorizationServer.issuer` value retained from discovery. Construct the URL rather than writing an alias into a template. This JavaScript fragment assumes `clientId`, `redirectUri` and `acceptedScope` come from your registration response and callback configuration:
+
+```javascript
+const base64url = bytes => btoa(String.fromCharCode(...bytes))
+  .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
+const challenge = base64url(new Uint8Array(await crypto.subtle.digest(
+  'SHA-256', new TextEncoder().encode(verifier))));
+const authorizationURL = new URL(authorizationServer.authorization_endpoint);
+authorizationURL.search = new URLSearchParams({
+  client_id: clientId, redirect_uri: redirectUri, response_type: 'code',
+  scope: acceptedScope, resource, state,
+  code_challenge: challenge, code_challenge_method: 'S256',
+}).toString();
+// Retain verifier, state and authorizationServer.issuer privately until callback validation.
+// Open authorizationURL.href in the user's browser; wait for their consent.
+```
+
 The user signs in on Port OS and reviews the requested permissions. Pause for the user; an agent must not approve its own grant, request passwords or manufacture a production sign-in identity. Local functional tests substitute an existing signed fixture identity at this boundary without changing production sign-in.
 
 After approval, Port OS navigates to the exact callback with code, state and iss. Reject a callback whose state or issuer does not match this attempt. Treat an error callback as a denied or failed authorization, not a code. Codes and pending consent expire after ten minutes and are single-use. Do not paste codes or credentials into shared chat or logs. Continue with [code exchange and token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md).

package/generated/public/docs/for-ai/guides/oauth-discovery.md

@@ -12,3 +12,17 @@ An MCP connector can start at https://api.portoperatingsystem.lol/mcp and follow
 Choose one supported [client registration method](/docs/for-ai/guides/oauth-client-registration.md), then follow the same [consent and callback steps](/docs/for-ai/guides/oauth-consent-and-callback.md). If metadata omits registration_endpoint, new DCR registration is unavailable; do not guess a replacement endpoint or silently switch to another client's credentials.
 
 See [scopes and resource rules](/docs/for-ai/guides/authorization-rules.md). Authorization-server scopes_supported describes server vocabulary; a particular client's accepted scopes can be narrower.
+
+## Carry discovery values into every request
+
+This JavaScript fragment initializes a REST connection. Keep `authorizationServer` and `resource` for the consent and token examples; the API alias is only the discovery starting point.
+
+```javascript
+const response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');
+if (!response.ok) throw new Error('OAuth discovery failed');
+const authorizationServer = await response.json();
+const resource = authorizationServer.issuer;
+const apiBase = authorizationServer.issuer;
+```
+
+For MCP, assign `resource` from the protected-resource metadata's `resource` field instead. Do not replace either value with the hostname you started from. A wrong `resource` can produce an `invalid_request` error callback even when client registration succeeded.

package/generated/public/docs/for-ai/guides/oauth-token-lifecycle.md

@@ -11,6 +11,21 @@ code_verifier=<this attempt's original verifier>
 resource=<the same canonical resource used for authorization>
 ```
 
+Continue with the same discovery values and verifier from the consent example. `code` below must be from a callback whose `state` and `iss` you validated; abort on any callback `error`:
+
+```javascript
+const tokenResponse = await fetch(authorizationServer.token_endpoint, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: new URLSearchParams({
+    grant_type: 'authorization_code', client_id: clientId, code,
+    redirect_uri: redirectUri, code_verifier: verifier, resource,
+  }),
+});
+if (!tokenResponse.ok) throw new Error('OAuth code exchange failed');
+const tokens = await tokenResponse.json(); // Store securely; do not print tokens.
+```
+
 Save access_token, refresh_token and returned scope in the connector's secure credential store. Public clients have no client secret. Use Authorization: Bearer <access_token> with REST requests or the MCP HTTP connection, according to that token's resource. A refresh token is never an API credential. [Scopes bound access; resource policies still apply](/docs/for-ai/guides/authorization-rules.md).
 
 Refresh with grant_type=refresh_token, client_id, refresh_token and the original resource at token_endpoint. Scope may stay the same or narrow; it cannot expand. Credentials rotate: store the newly returned refresh token atomically and stop using the previous one. A revoked or reused refresh token must not be retried in a loop. Reauthorize when the grant no longer permits the intended operation.

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

@@ -2,15 +2,15 @@
 
 First complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Keep the discovered API issuer and credentials in client configuration.
 
-1. GET /endpoints?owner=~caller&maxResults=25 with Authorization: Bearer <access_token>. A filter such as owner is required. Follow the returned continuation metadata until the authorized enumeration is complete. An empty list means valid access with no visible devices; guide the user to [add devices](/docs/for-ai/guides/adding-devices.md).
+1. GET /endpoints?owner=~caller&maxResults=25 with Authorization: Bearer <access_token>. Read [enumerateEndpoints](/docs/for-ai/operations/enumerateEndpoints.md) for the exact pagination and response fields. A filter such as owner is required. Follow the returned continuation metadata until the authorized enumeration is complete. An empty list means valid access with no visible devices; guide the user to [add devices](/docs/for-ai/guides/adding-devices.md).
 2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.
-3. Inspect its declared capability namespace and version. Follow [the capability directory](/docs/for-ai/capability-interfaces.md) to the exact message payload schema.
-4. With the user's intended action, POST /messages. Use the endpoint ID and message version you discovered, not the illustrative ID below.
+3. Inspect its declared capability namespace and version. A light declaring power 1.0 uses the [power guide](/docs/for-ai/capability-interfaces/power/1.0.md) and [turn-on payload schema](/docs/references/capability-interfaces/power/1.0/messages/turn-on.yaml). For other versions or capabilities, follow [the capability directory](/docs/for-ai/capability-interfaces.md).
+4. With the user's intended action, POST /messages. Read [sendMessage](/docs/for-ai/operations/sendMessage.md) and its linked request schema. Use the endpoint ID and message version you discovered, not the illustrative ID below.
 
 ```json
 {"target":{"type":"ENDPOINT","id":"port1/principals/example/endpoints/example-light"},"message":{"header":{"namespace":"port1/systems/zero/capability-interfaces/power","name":"turn-on","version":"1.0"},"body":{}}}
 ```
 
-The response's messageId identifies dispatch. It is not proof of physical state. Do not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [the operation contract](/docs/references/openapi.yaml) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.
+The response's messageId identifies dispatch. It is not proof of physical state. Do not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [enumerateEndpoints and its linked components](/docs/for-ai/operations/enumerateEndpoints.md) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.
 
 For first setup, test one explicitly selected safe light. Do not turn off all homes as a connectivity check. See [lighting](/docs/for-ai/guides/lighting.md), [first setup](/docs/for-ai/guides/first-setup.md) and [authorization rules](/docs/for-ai/guides/authorization-rules.md).

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

@@ -7,6 +7,7 @@ Read [authentication and DCR](/docs/for-ai/guides/authentication-and-dcr.md), th
 - [All task guides](/docs/for-ai/guides/index.md)
 - [Scopes and permission evaluation](/docs/for-ai/guides/authorization-rules.md)
 - [REST operation directory](/docs/for-ai/operations/index.md)
+- [Small REST schema files](/docs/for-ai/schemas.md)
 - [Capability directory](/docs/for-ai/capability-interfaces.md)
 - [OpenAPI YAML](/docs/references/openapi.yaml)
 - [Capability YAML index](/docs/references/capability-interfaces.yaml)

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

@@ -62,13 +62,13 @@ post:
       schema:
         type: string
       description: The ID of the endpoint group
-    - $ref: '#/components/parameters/IfMatch'
+    - $ref: /docs/references/parameters/IfMatch.json
   requestBody:
     required: true
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/AddEndpointGroupMembersRequest'
+          $ref: /docs/references/schemas/AddEndpointGroupMembersRequest.json
         example:
           memberEndpointIds: []
   responses:
@@ -76,74 +76,86 @@ post:
       description: Members addition accepted
       headers:
         ETag:
-          $ref: '#/components/headers/ETag'
+          $ref: /docs/references/headers/ETag.json
     '400':
       description: Invalid request payload
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Invalid request payload
-            type: BAD_REQUEST
+            code: BAD_REQUEST
+            family: BAD_REQUEST
     '401':
       description: Unauthorized - invalid or missing authentication token
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Authentication required
-            type: UNAUTHORIZED
+            code: UNAUTHORIZED
+            family: UNAUTHORIZED
     '403':
       description: Forbidden - insufficient permissions
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Insufficient permissions
-            type: FORBIDDEN
+            code: FORBIDDEN
+            family: FORBIDDEN
     '404':
       description: Endpoint group not found
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Resource not found
-            type: NOT_FOUND
+            code: NOT_FOUND
+            family: NOT_FOUND
     '412':
       description: The If-Match etag does not match the current group version; re-read the group and retry
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: group etag does not match; re-read the group and retry
-            type: PRECONDITION_FAILED
+            code: PRECONDITION_FAILED
             family: PRECONDITION_FAILED
     '428':
       description: The If-Match header is missing
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: If-Match header is required; send the group's etag
-            type: PRECONDITION_REQUIRED
+            code: PRECONDITION_REQUIRED
             family: PRECONDITION_REQUIRED
     '500':
       description: Internal server error
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Internal server error
-            type: INTERNAL
+            code: INTERNAL
+            family: INTERNAL_SERVER_ERROR
   x-portos-delegated: true
   x-portos-resource-permission: true
 ```
 
-Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).
+## Linked components
+
+- [ETag.json](/docs/references/headers/ETag.json)
+- [IfMatch.json](/docs/references/parameters/IfMatch.json)
+- [AddEndpointGroupMembersRequest.json](/docs/references/schemas/AddEndpointGroupMembersRequest.json)
+- [Error.json](/docs/references/schemas/Error.json)
+
+Follow only the linked components needed for this operation. [Schema directory](/docs/for-ai/schemas.md). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

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

@@ -51,7 +51,7 @@ post:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/AuthorizeDeviceRequest'
+          $ref: /docs/references/schemas/AuthorizeDeviceRequest.json
         example:
           user_code: ABCD-EFGH
           scopes:
@@ -63,7 +63,7 @@ post:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/AuthorizeDeviceResponse'
+            $ref: /docs/references/schemas/AuthorizeDeviceResponse.json
           example:
             success: true
     '400':
@@ -71,7 +71,7 @@ post:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/OAuthErrorResponse'
+            $ref: /docs/references/schemas/OAuthErrorResponse.json
           example:
             error: invalid_request
             error_description: user_code is required
@@ -80,7 +80,7 @@ post:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/OAuthErrorResponse'
+            $ref: /docs/references/schemas/OAuthErrorResponse.json
           example:
             error: invalid_request
             error_description: user_code is required
@@ -89,7 +89,7 @@ post:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/OAuthErrorResponse'
+            $ref: /docs/references/schemas/OAuthErrorResponse.json
           example:
             error: invalid_request
             error_description: user_code is required
@@ -100,4 +100,10 @@ post:
     - bearerAuth: []
 ```
 
-Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).
+## Linked components
+
+- [AuthorizeDeviceRequest.json](/docs/references/schemas/AuthorizeDeviceRequest.json)
+- [AuthorizeDeviceResponse.json](/docs/references/schemas/AuthorizeDeviceResponse.json)
+- [OAuthErrorResponse.json](/docs/references/schemas/OAuthErrorResponse.json)
+
+Follow only the linked components needed for this operation. [Schema directory](/docs/for-ai/schemas.md). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

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

@@ -57,6 +57,7 @@ get:
       required: true
       schema:
         type: string
+        x-enum-exempt: OAuth 2.0 response_type is the externally defined case-sensitive value code (RFC 6749).
         enum:
           - code
     - in: query
@@ -101,4 +102,8 @@ get:
   x-portos-delegated: false
 ```
 
-Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).
+## Linked components
+
+This operation uses inline schemas.
+
+Follow only the linked components needed for this operation. [Schema directory](/docs/for-ai/schemas.md). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

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

@@ -81,4 +81,8 @@ post:
   x-portos-delegated: false
 ```
 
-Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).
+## Linked components
+
+This operation uses inline schemas.
+
+Follow only the linked components needed for this operation. [Schema directory](/docs/for-ai/schemas.md). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

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

@@ -40,7 +40,7 @@ post:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/CreateEndpointGroupRequest'
+          $ref: /docs/references/schemas/CreateEndpointGroupRequest.json
         example:
           item:
             name:
@@ -51,11 +51,11 @@ post:
       description: Endpoint group created successfully
       headers:
         ETag:
-          $ref: '#/components/headers/ETag'
+          $ref: /docs/references/headers/ETag.json
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/CreateEndpointGroupResponse'
+            $ref: /docs/references/schemas/CreateEndpointGroupResponse.json
           example:
             id: port1/principals/user123/resources/abc-123
     '400':
@@ -63,39 +63,50 @@ post:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Invalid request payload
-            type: BAD_REQUEST
+            code: BAD_REQUEST
+            family: BAD_REQUEST
     '401':
       description: Unauthorized - invalid or missing authentication token
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Authentication required
-            type: UNAUTHORIZED
+            code: UNAUTHORIZED
+            family: UNAUTHORIZED
     '403':
       description: Forbidden - insufficient permissions
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Insufficient permissions
-            type: FORBIDDEN
+            code: FORBIDDEN
+            family: FORBIDDEN
     '500':
       description: Internal server error
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: /docs/references/schemas/Error.json
           example:
             message: Internal server error
-            type: INTERNAL
+            code: INTERNAL
+            family: INTERNAL_SERVER_ERROR
   x-portos-delegated: true
   x-portos-resource-permission: true
 ```
 
-Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).
+## Linked components
+
+- [ETag.json](/docs/references/headers/ETag.json)
+- [CreateEndpointGroupRequest.json](/docs/references/schemas/CreateEndpointGroupRequest.json)
+- [CreateEndpointGroupResponse.json](/docs/references/schemas/CreateEndpointGroupResponse.json)
+- [Error.json](/docs/references/schemas/Error.json)
+
+Follow only the linked components needed for this operation. [Schema directory](/docs/for-ai/schemas.md). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).