@portpowered/reference-data 0.4.3 → 0.4.5

package/README.md

@@ -1,6 +1,6 @@
 ---
 author: Port OS Team
-last modified: 2026, october, 7
+last modified: 2026, october, 9
 ---
 
 # Port OS reference data

package/generated/guides.json

@@ -8,7 +8,7 @@
   {
     "id": "authentication-and-dcr",
     "title": "Authentication and dynamic client registration",
-    "content": "# Authentication and dynamic client registration\n\nAll 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.\n\nThe complete walkthrough below is generated from the canonical components linked here. Read it in one document, or reference the individual components from your connector:\n\n1. [Discover endpoints and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).\n2. [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.\n3. [Obtain user consent and validate the callback](/docs/for-ai/guides/oauth-consent-and-callback.md). PKCE S256 is required. Pause for the user to sign in and approve access.\n4. [Exchange, refresh and revoke tokens](/docs/for-ai/guides/oauth-token-lifecycle.md). Keep the same canonical resource through authorization, exchange and refresh.\n5. [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.\n\nRead [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.\n\n## Discover the OAuth server and choose REST or MCP\n\nThis 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.\n\n| Interface | API destination | OAuth resource |\n| --- | --- | --- |\n| REST | The returned issuer, plus the documented operation path | The exact returned issuer |\n| MCP | The returned issuer plus /mcp, Streamable HTTP | The resource returned by /.well-known/oauth-protected-resource/mcp, normally issuer plus /mcp |\n\nAn 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.\n\nChoose 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.\n\nSee [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.\n\n### Carry discovery values into every request\n\nThis 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.\n\n```javascript\nconst response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');\nif (!response.ok) throw new Error('OAuth discovery failed');\nconst authorizationServer = await response.json();\nconst resource = authorizationServer.issuer;\nconst apiBase = authorizationServer.issuer;\n```\n\nFor 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.\n\nCanonical component: [Discover the OAuth server and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).\n\n## Register an OAuth client with DCR or CIMD\n\nStart 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).\n\n### DCR: public clients\n\nPOST application/json to the discovered registration_endpoint:\n\n```json\n{\"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\"}\n```\n\nUse 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.\n\nSuccess 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.\n\nThe 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.\n\nDefault 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.\n\n### CIMD: allowlisted metadata clients\n\nA 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.\n\nClient_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.\n\nCanonical component: [Register an OAuth client with DCR or CIMD](/docs/for-ai/guides/oauth-client-registration.md).\n\n## Obtain user consent and validate the OAuth callback\n\nUse 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.\n\n1. Start the callback handler the client controls. For a loopback callback, bind its listener locally before opening authorization.\n2. 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.\n3. 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.\n\n```text\nclient_id=<registered ID or supported CIMD metadata URL>\nredirect_uri=<exact registered callback>\nresponse_type=code\nscope=<requested subset of the client's accepted scopes>\nresource=<chosen canonical REST or MCP resource>\nstate=<random client state>\ncode_challenge=<S256 challenge>\ncode_challenge_method=S256\n```\n\nFor 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:\n\n```javascript\nconst base64url = bytes => btoa(String.fromCharCode(...bytes))\n  .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');\nconst verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));\nconst state = base64url(crypto.getRandomValues(new Uint8Array(32)));\nconst challenge = base64url(new Uint8Array(await crypto.subtle.digest(\n  'SHA-256', new TextEncoder().encode(verifier))));\nconst authorizationURL = new URL(authorizationServer.authorization_endpoint);\nauthorizationURL.search = new URLSearchParams({\n  client_id: clientId, redirect_uri: redirectUri, response_type: 'code',\n  scope: acceptedScope, resource, state,\n  code_challenge: challenge, code_challenge_method: 'S256',\n}).toString();\n// Retain verifier, state and authorizationServer.issuer privately until callback validation.\n// Open authorizationURL.href in the user's browser; wait for their consent.\n```\n\nThe 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.\n\nAfter 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).\n\nCanonical component: [Obtain user consent and validate the OAuth callback](/docs/for-ai/guides/oauth-consent-and-callback.md).\n\n## Exchange, refresh and revoke scoped OAuth tokens\n\nComplete [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:\n\n```text\ngrant_type=authorization_code\nclient_id=<client ID used for authorization>\ncode=<validated callback code>\nredirect_uri=<the same exact callback>\ncode_verifier=<this attempt's original verifier>\nresource=<the same canonical resource used for authorization>\n```\n\nContinue 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`:\n\n```javascript\nconst tokenResponse = await fetch(authorizationServer.token_endpoint, {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({\n    grant_type: 'authorization_code', client_id: clientId, code,\n    redirect_uri: redirectUri, code_verifier: verifier, resource,\n  }),\n});\nif (!tokenResponse.ok) throw new Error('OAuth code exchange failed');\nconst tokens = await tokenResponse.json(); // Store securely; do not print tokens.\n```\n\nSave 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).\n\nRefresh 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.\n\nRevoke 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.\n\nRead [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.\n\nCanonical component: [Exchange, refresh and revoke scoped OAuth tokens](/docs/for-ai/guides/oauth-token-lifecycle.md).\n\n## Scopes and authorization rules\n\nAuthentication 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.\n\nFor 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.\n\n| Task | Scope |\n| --- | --- |\n| Enumerate or query endpoints/routes | endpoint:read |\n| Modify endpoints/routes | endpoint:write |\n| Send a device message | message:send |\n| Read groups and relationships | group:read |\n| Manage group membership | group:manage |\n| Read subscriptions | subscription:read |\n| Create/update/delete subscriptions | subscription:write |\n\nOther 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.\n\nThe 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.\n\nA 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.\n\nAn 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.\n\nSee [troubleshooting](/docs/for-ai/guides/troubleshooting.md).\n\nCanonical component: [Scopes and authorization rules](/docs/for-ai/guides/authorization-rules.md).\n",
+    "content": "# Authentication and dynamic client registration\n\nAll 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.\n\nChoose one reading path. This complete walkthrough already includes discovery, registration, consent, token lifecycle and authorization rules below; you do not need to fetch those component links again. If your connector already implements some steps, read only the missing components instead. Both paths use the same canonical instructions.\n\nFor REST, use the discovered issuer as the OAuth resource. For MCP, use the MCP protected-resource metadata. Keep that choice through authorization, exchange and refresh. If you chose the wrong transport, start a new authorization flow for the correct resource; refresh does not switch audiences.\n\nWalkthrough steps (the linked components are also included below):\n\n1. [Discover endpoints and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).\n2. [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.\n3. [Obtain user consent and validate the callback](/docs/for-ai/guides/oauth-consent-and-callback.md). PKCE S256 is required. Pause for the user to sign in and approve access.\n4. [Exchange, refresh and revoke tokens](/docs/for-ai/guides/oauth-token-lifecycle.md). Keep the same canonical resource through authorization, exchange and refresh.\n5. [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.\n\nRead [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.\n\n## Discover the OAuth server and choose REST or MCP\n\nThis 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.\n\n| Interface | API destination | OAuth resource |\n| --- | --- | --- |\n| REST | The returned issuer, plus the documented operation path | The exact returned issuer |\n| MCP | The returned issuer plus /mcp, Streamable HTTP | The resource returned by /.well-known/oauth-protected-resource/mcp, normally issuer plus /mcp |\n\nAn 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.\n\nChoose the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.\n\nChoose 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.\n\nSee [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.\n\n### Carry discovery values into every request\n\nThis 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.\n\n```javascript\nconst response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');\nif (!response.ok) throw new Error('OAuth discovery failed');\nconst authorizationServer = await response.json();\nconst resource = authorizationServer.issuer;\nconst apiBase = authorizationServer.issuer;\n```\n\nFor 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.\n\nCanonical component: [Discover the OAuth server and choose REST or MCP](/docs/for-ai/guides/oauth-discovery.md).\n\n## Register an OAuth client with DCR or CIMD\n\nStart 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).\n\n### DCR: public clients\n\nPOST application/json to the discovered registration_endpoint:\n\n```json\n{\"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\"}\n```\n\nUse 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.\n\nSuccess 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.\n\nThe 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.\n\nDefault 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.\n\n### CIMD: allowlisted metadata clients\n\nA 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.\n\nClient_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.\n\nCanonical component: [Register an OAuth client with DCR or CIMD](/docs/for-ai/guides/oauth-client-registration.md).\n\n## Obtain user consent and validate the OAuth callback\n\nUse 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.\n\n1. Start the callback handler the client controls. For a loopback callback, bind its listener locally before opening authorization.\n2. 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.\n3. 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.\n\n```text\nclient_id=<registered ID or supported CIMD metadata URL>\nredirect_uri=<exact registered callback>\nresponse_type=code\nscope=<requested subset of the client's accepted scopes>\nresource=<chosen canonical REST or MCP resource>\nstate=<random client state>\ncode_challenge=<S256 challenge>\ncode_challenge_method=S256\n```\n\nFor 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:\n\n```javascript\nconst base64url = bytes => btoa(String.fromCharCode(...bytes))\n  .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');\nconst verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));\nconst state = base64url(crypto.getRandomValues(new Uint8Array(32)));\nconst challenge = base64url(new Uint8Array(await crypto.subtle.digest(\n  'SHA-256', new TextEncoder().encode(verifier))));\nconst authorizationURL = new URL(authorizationServer.authorization_endpoint);\nauthorizationURL.search = new URLSearchParams({\n  client_id: clientId, redirect_uri: redirectUri, response_type: 'code',\n  scope: acceptedScope, resource, state,\n  code_challenge: challenge, code_challenge_method: 'S256',\n}).toString();\n// Retain verifier, state and authorizationServer.issuer privately until callback validation.\n// Open authorizationURL.href in the user's browser; wait for their consent.\n```\n\nThe 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.\n\nAfter 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).\n\nCanonical component: [Obtain user consent and validate the OAuth callback](/docs/for-ai/guides/oauth-consent-and-callback.md).\n\n## Exchange, refresh and revoke scoped OAuth tokens\n\nComplete [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:\n\n```text\ngrant_type=authorization_code\nclient_id=<client ID used for authorization>\ncode=<validated callback code>\nredirect_uri=<the same exact callback>\ncode_verifier=<this attempt's original verifier>\nresource=<the same canonical resource used for authorization>\n```\n\nContinue 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`:\n\n```javascript\nconst tokenResponse = await fetch(authorizationServer.token_endpoint, {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({\n    grant_type: 'authorization_code', client_id: clientId, code,\n    redirect_uri: redirectUri, code_verifier: verifier, resource,\n  }),\n});\nif (!tokenResponse.ok) throw new Error('OAuth code exchange failed');\nconst tokens = await tokenResponse.json(); // Store securely; do not print tokens.\n```\n\nSave 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).\n\nRefresh 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.\n\nRevoke 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.\n\nRead [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.\n\nCanonical component: [Exchange, refresh and revoke scoped OAuth tokens](/docs/for-ai/guides/oauth-token-lifecycle.md).\n\n## Scopes and authorization rules\n\nAuthentication 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.\n\nFor 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.\n\n| Task | Scope |\n| --- | --- |\n| Enumerate or query endpoints/routes | endpoint:read |\n| Modify endpoints/routes | endpoint:write |\n| Send a device message | message:send |\n| Read groups and relationships | group:read |\n| Manage group membership | group:manage |\n| Read subscriptions | subscription:read |\n| Create/update/delete subscriptions | subscription:write |\n\nOther 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.\n\nThe 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.\n\nA 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.\n\nAn 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.\n\nSee [troubleshooting](/docs/for-ai/guides/troubleshooting.md).\n\nCanonical component: [Scopes and authorization rules](/docs/for-ai/guides/authorization-rules.md).\n",
     "setupPrompt": null
   },
   {
@@ -26,7 +26,7 @@
   {
     "id": "connect-agent",
     "title": "Connect any supported agent to Port OS",
-    "content": "# Connect any supported agent to Port OS\n\nUse these common components for Muse, Grok, Claude, a custom REST agent or an MCP connector. The product name does not change the authorization protocol or permissions. Check your client's current capabilities before assuming it supports a particular registration method.\n\nCopy this prompt into a client that can retrieve public documents:\n\n> Read https://app.portoperatingsystem.lol/docs/for-ai/guides/connect-agent.md. Discover Port OS authentication, choose REST or MCP and a registration method supported by this client, and help me connect. Pause for me to sign in and approve the requested access, then list only devices I can access. Do not claim device control until its result is observed.\n\n| Component | Input | Result |\n| --- | --- | --- |\n| [Discovery and transport](/docs/for-ai/guides/oauth-discovery.md) | Public API/MCP URL | Canonical issuer, endpoints and REST/MCP resource |\n| [DCR or CIMD registration](/docs/for-ai/guides/oauth-client-registration.md) | Client-supported method and controlled callback | Client identity and accepted profile, without device access |\n| [User consent and callback](/docs/for-ai/guides/oauth-consent-and-callback.md) | Client ID, callback, resource and least scopes | Validated one-use authorization code |\n| [Token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md) | Code and original PKCE verifier | Scoped access, refresh rotation and revocation |\n| [Authorization rules](/docs/for-ai/guides/authorization-rules.md) | Token scopes and customer's permissions | Effective authority and an explanation of denials |\n| [First setup](/docs/for-ai/guides/first-setup.md) | Authorized connection | Device discovery and one safe verification |\n\nAn MCP-capable client normally manages OAuth and secure token storage itself; supply the MCP URL and complete its consent flow. A REST agent needs an execution environment with HTTP requests, a real callback listener, cryptographic random generation and secure token storage. If the client cannot receive a callback or securely retain credentials, explain the missing capability instead of inventing a bypass.\n\nClient-specific screens can provide UI settings or support notes and link to this table. They must not maintain their own copies of DCR, PKCE, scope, callback or revocation instructions. Actual client/version compatibility and vendor identity require separate validation; the shared guide makes no verified Muse/Grok claim.\n",
+    "content": "# Connect any supported agent to Port OS\n\nUse these common components for Muse, Grok, Claude, a custom REST agent or an MCP connector. The product name does not change the authorization protocol or permissions. Check your client's current capabilities before assuming it supports a particular registration method.\n\nFor a new REST connection, read the [complete authentication walkthrough](/docs/for-ai/guides/authentication-and-dcr.md), then the [REST quickstart](/docs/for-ai/guides/quickstart.md). The walkthrough includes the OAuth components in the table below; you can skip their separate files. For an existing connector, use the table to read only the component you need. This directory is a set of alternatives, not a checklist of required downloads.\n\nCopy this prompt into a client that can retrieve public documents:\n\n> Read https://app.portoperatingsystem.lol/docs/for-ai/guides/connect-agent.md. Discover Port OS authentication, choose REST or MCP and a registration method supported by this client, and help me connect. Pause for me to sign in and approve the requested access, then list only devices I can access. Do not claim device control until its result is observed.\n\n| Component | Input | Result |\n| --- | --- | --- |\n| [Discovery and transport](/docs/for-ai/guides/oauth-discovery.md) | Public API/MCP URL | Canonical issuer, endpoints and REST/MCP resource |\n| [DCR or CIMD registration](/docs/for-ai/guides/oauth-client-registration.md) | Client-supported method and controlled callback | Client identity and accepted profile, without device access |\n| [User consent and callback](/docs/for-ai/guides/oauth-consent-and-callback.md) | Client ID, callback, resource and least scopes | Validated one-use authorization code |\n| [Token lifecycle](/docs/for-ai/guides/oauth-token-lifecycle.md) | Code and original PKCE verifier | Scoped access, refresh rotation and revocation |\n| [Authorization rules](/docs/for-ai/guides/authorization-rules.md) | Token scopes and customer's permissions | Effective authority and an explanation of denials |\n| [First setup](/docs/for-ai/guides/first-setup.md) | Authorized connection | Device discovery and one safe verification |\n\nAn MCP-capable client normally manages OAuth and secure token storage itself; supply the MCP URL and complete its consent flow. A REST agent needs an execution environment with HTTP requests, a real callback listener, cryptographic random generation and secure token storage. If the client cannot receive a callback or securely retain credentials, explain the missing capability instead of inventing a bypass.\n\nClient-specific screens can provide UI settings or support notes and link to this table. They must not maintain their own copies of DCR, PKCE, scope, callback or revocation instructions. Actual client/version compatibility and vendor identity require separate validation; the shared guide makes no verified Muse/Grok claim.\n",
     "setupPrompt": "Read https://app.portoperatingsystem.lol/docs/for-ai/guides/connect-agent.md. Discover Port OS authentication, choose REST or MCP and a registration method supported by this client, and help me connect. Pause for me to sign in and approve the requested access, then list only devices I can access. Do not claim device control until its result is observed."
   },
   {
@@ -86,7 +86,7 @@
   {
     "id": "oauth-discovery",
     "title": "Discover the OAuth server and choose REST or MCP",
-    "content": "# Discover the OAuth server and choose REST or MCP\n\nThis 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.\n\n| Interface | API destination | OAuth resource |\n| --- | --- | --- |\n| REST | The returned issuer, plus the documented operation path | The exact returned issuer |\n| MCP | The returned issuer plus /mcp, Streamable HTTP | The resource returned by /.well-known/oauth-protected-resource/mcp, normally issuer plus /mcp |\n\nAn 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.\n\nChoose 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.\n\nSee [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.\n\n## Carry discovery values into every request\n\nThis 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.\n\n```javascript\nconst response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');\nif (!response.ok) throw new Error('OAuth discovery failed');\nconst authorizationServer = await response.json();\nconst resource = authorizationServer.issuer;\nconst apiBase = authorizationServer.issuer;\n```\n\nFor 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.\n",
+    "content": "# Discover the OAuth server and choose REST or MCP\n\nThis 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.\n\n| Interface | API destination | OAuth resource |\n| --- | --- | --- |\n| REST | The returned issuer, plus the documented operation path | The exact returned issuer |\n| MCP | The returned issuer plus /mcp, Streamable HTTP | The resource returned by /.well-known/oauth-protected-resource/mcp, normally issuer plus /mcp |\n\nAn 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.\n\nChoose the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.\n\nChoose 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.\n\nSee [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.\n\n## Carry discovery values into every request\n\nThis 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.\n\n```javascript\nconst response = await fetch('https://api.portoperatingsystem.lol/.well-known/oauth-authorization-server');\nif (!response.ok) throw new Error('OAuth discovery failed');\nconst authorizationServer = await response.json();\nconst resource = authorizationServer.issuer;\nconst apiBase = authorizationServer.issuer;\n```\n\nFor 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.\n",
     "setupPrompt": null
   },
   {
@@ -104,7 +104,7 @@
   {
     "id": "quickstart",
     "title": "Verify the connection and control one light",
-    "content": "# Verify the connection and control one light\n\nFirst complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Keep the discovered API issuer and credentials in client configuration.\n\n1. 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).\n2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.\n3. 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).\n4. 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.\n\n```json\n{\"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\":{}}}\n```\n\nThe 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.\n\nFor 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).\n",
+    "content": "# Verify the connection and control one light\n\nFirst complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Keep the discovered API issuer and credentials in client configuration.\n\n1. 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).\n2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.\n3. 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).\n4. With the user's intended action, POST /messages with Authorization: Bearer <access_token> and Content-Type: application/json. Send the request object below as the JSON body, without a surrounding `body` field or a JSON string. 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.\n\n```json\n{\"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\":{}}}\n```\n\nHTTP 200 acknowledges acceptance. An asynchronous request can return `{\"messageId\":\"\"}` without a `message`; the empty ID is valid and does not provide a durable receipt or retry deduplication. When a unary response message is present, `messageId` identifies that response. Neither response proves physical state. After a lost response, treat the outcome as unknown and inspect state before deciding whether another action is safe.\n\nDo 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.\n\nFor 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).\n",
     "setupPrompt": null
   },
   {

package/generated/openapi.json

@@ -9826,14 +9826,14 @@
         },
         "responses": {
           "200": {
-            "description": "Message sent successfully",
+            "description": "Request accepted; an asynchronous acknowledgment may have an empty messageId and no message. Verify device state separately.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateMessageResponse"
                 },
                 "example": {
-                  "messageId": "example-dispatch-id"
+                  "messageId": ""
                 }
               }
             }
@@ -10106,14 +10106,14 @@
         },
         "responses": {
           "200": {
-            "description": "Message sent successfully",
+            "description": "Request accepted; an asynchronous acknowledgment may have an empty messageId and no message. Verify device state separately.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateMessageResponse"
                 },
                 "example": {
-                  "messageId": "example-dispatch-id"
+                  "messageId": ""
                 }
               }
             }
@@ -26762,7 +26762,7 @@
         "properties": {
           "messageId": {
             "type": "string",
-            "description": "The ID of the created message"
+            "description": "Identifies the unary response message when one is returned. An accepted asynchronous request can return an empty string with no message. This field does not provide a durable dispatch receipt, retry deduplication or proof of observed device state."
           },
           "message": {
             "$ref": "#/components/schemas/Message",

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

@@ -2,7 +2,11 @@
 
 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.
 
-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:
+Choose one reading path. This complete walkthrough already includes discovery, registration, consent, token lifecycle and authorization rules below; you do not need to fetch those component links again. If your connector already implements some steps, read only the missing components instead. Both paths use the same canonical instructions.
+
+For REST, use the discovered issuer as the OAuth resource. For MCP, use the MCP protected-resource metadata. Keep that choice through authorization, exchange and refresh. If you chose the wrong transport, start a new authorization flow for the correct resource; refresh does not switch audiences.
+
+Walkthrough steps (the linked components are also included below):
 
 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.
@@ -23,6 +27,8 @@ This discovery step is shared by every client. The deployed pilot API is https:/
 
 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 the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
+
 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.

package/generated/public/docs/for-ai/guides/connect-agent.md

@@ -2,6 +2,8 @@
 
 Use these common components for Muse, Grok, Claude, a custom REST agent or an MCP connector. The product name does not change the authorization protocol or permissions. Check your client's current capabilities before assuming it supports a particular registration method.
 
+For a new REST connection, read the [complete authentication walkthrough](/docs/for-ai/guides/authentication-and-dcr.md), then the [REST quickstart](/docs/for-ai/guides/quickstart.md). The walkthrough includes the OAuth components in the table below; you can skip their separate files. For an existing connector, use the table to read only the component you need. This directory is a set of alternatives, not a checklist of required downloads.
+
 Copy this prompt into a client that can retrieve public documents:
 
 > Read https://app.portoperatingsystem.lol/docs/for-ai/guides/connect-agent.md. Discover Port OS authentication, choose REST or MCP and a registration method supported by this client, and help me connect. Pause for me to sign in and approve the requested access, then list only devices I can access. Do not claim device control until its result is observed.

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

@@ -1,5 +1,7 @@
 # User guides
 
+This is a directory, not a required reading checklist. For a new REST connection, read [the complete authentication walkthrough](/docs/for-ai/guides/authentication-and-dcr.md) and [the quickstart](/docs/for-ai/guides/quickstart.md). The walkthrough already includes its OAuth components. Read individual components only when you need a specific step.
+
 - [Add devices through provider linking](/docs/for-ai/guides/adding-devices.md)
 - [Authentication and dynamic client registration](/docs/for-ai/guides/authentication-and-dcr.md)
 - [Scopes and authorization rules](/docs/for-ai/guides/authorization-rules.md)

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

@@ -9,6 +9,8 @@ This discovery step is shared by every client. The deployed pilot API is https:/
 
 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 the transport before authorizing. Keep its resource unchanged through authorization, token exchange and refresh. If a REST request fails because you authorized the MCP resource (or the reverse), obtain a new user authorization for the correct resource. Refresh cannot change the token's audience.
+
 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.

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

@@ -5,12 +5,14 @@ First complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Kee
 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. 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.
+4. With the user's intended action, POST /messages with Authorization: Bearer <access_token> and Content-Type: application/json. Send the request object below as the JSON body, without a surrounding `body` field or a JSON string. 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 [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.
+HTTP 200 acknowledges acceptance. An asynchronous request can return `{"messageId":""}` without a `message`; the empty ID is valid and does not provide a durable receipt or retry deduplication. When a unary response message is present, `messageId` identifies that response. Neither response proves physical state. After a lost response, treat the outcome as unknown and inspect state before deciding whether another action is safe.
+
+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

@@ -1,17 +1,24 @@
 # Port OS: start here for agents
 
-Read [authentication and DCR](/docs/for-ai/guides/authentication-and-dcr.md), then [the quickstart](/docs/for-ai/guides/quickstart.md). Register a public client, open the user authorization URL, wait for the user to consent, verify the callback, then exchange its code with PKCE. Registration alone gives no device access. Never request the user’s Google password or reuse another client’s tokens.
+## New REST connection
 
-## Documentation tree
+Read [the complete authentication walkthrough](/docs/for-ai/guides/authentication-and-dcr.md), then [the REST quickstart](/docs/for-ai/guides/quickstart.md). The walkthrough includes discovery, DCR/CIMD, consent, callback, token lifecycle and permission rules. You do not need to read their separate component files again. Follow an operation or capability link from the quickstart only when you need its exact contract.
 
-- [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)
+Registration alone gives no device access. Wait for user consent and validate the callback before exchanging its code with PKCE. Never request the user’s Google password or reuse another client’s tokens.
+
+## Existing connector or MCP
+
+Use [the shared connection guide](/docs/for-ai/guides/connect-agent.md) to select the transport and only the components your client needs. REST and MCP use different OAuth resources; choose before authorization and retain the resource through exchange and refresh.
+
+## Documentation tree: look up what you need
+
+- [Task/component guide directory](/docs/for-ai/guides/index.md): alternatives, not a required reading checklist
+- [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
+- [Authorization inventory](/docs/references/authorization.yaml): machine-readable scope/policy rules
+- [Full OpenAPI YAML](/docs/references/openapi.yaml): comprehensive lookup and SDK generation; unnecessary for the quickstart
 - [Capability YAML index](/docs/references/capability-interfaces.yaml)
-- [Authorization inventory](/docs/references/authorization.yaml)
 - [Release manifest](/docs/references/manifest.json)
 
 These links are public UTF-8 documents. You do not need JavaScript, sign-in, or a repository checkout to read them. Device data still requires consent and resource permission.

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

@@ -114,13 +114,15 @@ post:
             body: {}
   responses:
     '200':
-      description: Message sent successfully
+      description: >-
+        Request accepted; an asynchronous acknowledgment may have an empty messageId and no message.
+        Verify device state separately.
       content:
         application/json:
           schema:
             $ref: /docs/references/schemas/CreateMessageResponse.json
           example:
-            messageId: example-dispatch-id
+            messageId: ''
     '400':
       description: Invalid request payload or plugin dispatch request error
       content:

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

@@ -114,13 +114,15 @@ post:
             body: {}
   responses:
     '200':
-      description: Message sent successfully
+      description: >-
+        Request accepted; an asynchronous acknowledgment may have an empty messageId and no message.
+        Verify device state separately.
       content:
         application/json:
           schema:
             $ref: /docs/references/schemas/CreateMessageResponse.json
           example:
-            messageId: example-dispatch-id
+            messageId: ''
     '400':
       description: Invalid request payload or plugin dispatch request error
       content:

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

@@ -1,12 +1,12 @@
 {
   "package": "@portpowered/reference-data",
   "goModule": "github.com/portpowered/portos-reference-data",
-  "version": "0.4.3",
-  "sourceCommit": "eecb0269b4626c38f646c4ed03b55a793c511bbd",
+  "version": "0.4.5",
+  "sourceCommit": "07fdcc4ef4f322950ecb617ffaf47a79b9f0a122",
   "sourceInputState": "committed",
-  "sourceInputSHA256": "19728ad478ab3d79f8f50f3d816de492ad6dd9f3361a2a1cd097448b5264b260",
+  "sourceInputSHA256": "d8183268527e9f3de34ec8374b1007a4ed48cc0d4255dd8c3bc5822f10e57818",
   "sourceInputCount": 735,
-  "assetSetSHA256": "47173fdb53c1c85580bf61d001555c969acf468d8dd1ffe33dfc84de92f6eaec",
+  "assetSetSHA256": "bae4942d5ad905c28c49cd3967c8e3c24f54db3dc36c90119208fd9c12ef1adc",
   "files": [
     {
       "path": "/docs/for-ai/capability-interfaces.md",
@@ -1184,8 +1184,8 @@
     {
       "path": "/docs/for-ai/guides/authentication-and-dcr.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 16740,
-      "sha256": "69ff1fda5f5443ed1fa5c21abdfa5dda5c73b1edc6e54b9f056776f881d7dc80",
+      "bytes": 17581,
+      "sha256": "32616ea9e28a675efe2c2dee51f149eefec2dead1af2b5275b91c3c9bae3a7be",
       "links": [
         "/docs/for-ai/guides/authorization-rules.md",
         "/docs/for-ai/guides/first-setup.md",
@@ -1227,15 +1227,17 @@
     {
       "path": "/docs/for-ai/guides/connect-agent.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 2474,
-      "sha256": "2ace8142f363edcf8d48039f463fd2528307ffac1c3238301d85e8955b234e6a",
+      "bytes": 2919,
+      "sha256": "5aa9459297c58a1b648b2385a546b25814567c4bdbaef30ab03ffe909f73d391",
       "links": [
+        "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/guides/authorization-rules.md",
         "/docs/for-ai/guides/first-setup.md",
         "/docs/for-ai/guides/oauth-client-registration.md",
         "/docs/for-ai/guides/oauth-consent-and-callback.md",
         "/docs/for-ai/guides/oauth-discovery.md",
-        "/docs/for-ai/guides/oauth-token-lifecycle.md"
+        "/docs/for-ai/guides/oauth-token-lifecycle.md",
+        "/docs/for-ai/guides/quickstart.md"
       ]
     },
     {
@@ -1270,8 +1272,8 @@
     {
       "path": "/docs/for-ai/guides/index.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 1838,
-      "sha256": "becf671ec3d3e46eafd6dfe8ac99e14b780534fc435a55c1b997d5b32498cfa5",
+      "bytes": 2190,
+      "sha256": "936e643766ce6a3c245a03f91b8a1b74087ce4cfa237e6f94e8e0939e92a6720",
       "links": [
         "/docs/for-ai/guides/adding-devices.md",
         "/docs/for-ai/guides/authentication-and-dcr.md",
@@ -1366,8 +1368,8 @@
     {
       "path": "/docs/for-ai/guides/oauth-discovery.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 2545,
-      "sha256": "e04f8ab874da6c399c59c7f4618da37f99160f87c7f0adf39800486d6fb3192f",
+      "bytes": 2850,
+      "sha256": "588efd7396d2b5b600eb2bd085d1c947afc429fb5f383cc3093734e9ce2a27c7",
       "links": [
         "/docs/for-ai/guides/authorization-rules.md",
         "/docs/for-ai/guides/oauth-client-registration.md",
@@ -1401,8 +1403,8 @@
     {
       "path": "/docs/for-ai/guides/quickstart.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 2650,
-      "sha256": "34606cd8f50344acfbc3becd901518e2b83e2b0b2666d4ce59579b7d6d564058",
+      "bytes": 3180,
+      "sha256": "a230400fa9f48bd5b629bad119bf079cbdf2faabee6270137ae0e9b2fa0b0fce",
       "links": [
         "/docs/for-ai/capability-interfaces.md",
         "/docs/for-ai/capability-interfaces/power/1.0.md",
@@ -1475,12 +1477,12 @@
     {
       "path": "/docs/for-ai/index.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 1185,
-      "sha256": "ed6011cbe96c70b27fe8ec486c24beb69737ec570b14368b580ba855179e1383",
+      "bytes": 1973,
+      "sha256": "303ac8481dfd46c092f1e9fe988740878d146d0194404b309eeb554f4eb2973c",
       "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/connect-agent.md",
         "/docs/for-ai/guides/index.md",
         "/docs/for-ai/guides/quickstart.md",
         "/docs/for-ai/operations/index.md",
@@ -2649,8 +2651,8 @@
     {
       "path": "/docs/for-ai/operations/sendMessage.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 9642,
-      "sha256": "11f1a2ba1c1e57b0cf283564d210057545fe22b83eb1fba8baf562ee1be351c2",
+      "bytes": 9743,
+      "sha256": "e9c1092a4809c9298d03d3bf0baec094125ea2f28ce2eddea031d2d8252e4f6d",
       "links": [
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/schemas.md",
@@ -2662,8 +2664,8 @@
     {
       "path": "/docs/for-ai/operations/sendMessageLegacyAlias.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 9913,
-      "sha256": "d2be61f7dc58f08addaf59ae65317eb121cb003ac91a9cea20280b05ea769baa",
+      "bytes": 10014,
+      "sha256": "0194b7b87f6ead4e405250f0e3710d89447e7d56e0df8efad9b57f800bf9a8af",
       "links": [
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/schemas.md",
@@ -7350,8 +7352,8 @@
     {
       "path": "/docs/references/openapi.yaml",
       "contentType": "application/yaml; charset=utf-8",
-      "bytes": 757134,
-      "sha256": "35386f69ebbd31904ad9d63fbf5aecbea8648f0f6ff2925e1653ff60c3fd9387",
+      "bytes": 757609,
+      "sha256": "a6db7cfd7943b4298c07af9dbf1078bcccc15725fa3a4e7a329f92c18e19c89c",
       "links": []
     },
     {
@@ -8407,8 +8409,8 @@
     {
       "path": "/docs/references/schemas/CreateMessageResponse.json",
       "contentType": "application/json",
-      "bytes": 580,
-      "sha256": "c75f34dcf1e8efdcceb0f584d12e25159ee65165cb2ccfff7d8331a18d69d7a2",
+      "bytes": 798,
+      "sha256": "d97a132f4abb5f70006e0f1340dd04a8d76e954c19b5bb557e86360a68071be5",
       "links": []
     },
     {

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

@@ -7136,13 +7136,15 @@ paths:
                 body: {}
       responses:
         '200':
-          description: Message sent successfully
+          description: >-
+            Request accepted; an asynchronous acknowledgment may have an empty messageId and no
+            message. Verify device state separately.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/CreateMessageResponse'
               example:
-                messageId: example-dispatch-id
+                messageId: ''
         '400':
           description: Invalid request payload or plugin dispatch request error
           content:
@@ -7366,13 +7368,15 @@ paths:
                 body: {}
       responses:
         '200':
-          description: Message sent successfully
+          description: >-
+            Request accepted; an asynchronous acknowledgment may have an empty messageId and no
+            message. Verify device state separately.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/CreateMessageResponse'
               example:
-                messageId: example-dispatch-id
+                messageId: ''
         '400':
           description: Invalid request payload or plugin dispatch request error
           content:
@@ -20851,7 +20855,10 @@ components:
       properties:
         messageId:
           type: string
-          description: The ID of the created message
+          description: >-
+            Identifies the unary response message when one is returned. An accepted asynchronous
+            request can return an empty string with no message. This field does not provide a
+            durable dispatch receipt, retry deduplication or proof of observed device state.
         message:
           $ref: '#/components/schemas/Message'
           description: >-

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

@@ -7,7 +7,7 @@
   "properties": {
     "messageId": {
       "type": "string",
-      "description": "The ID of the created message"
+      "description": "Identifies the unary response message when one is returned. An accepted asynchronous request can return an empty string with no message. This field does not provide a durable dispatch receipt, retry deduplication or proof of observed device state."
     },
     "message": {
       "$ref": "/docs/references/schemas/Message.json",

package/package.json

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