@portpowered/reference-data 0.4.2 → 0.4.4

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
@@ -47,6 +47,6 @@ Import `@portpowered/reference-data/capabilities`, `@portpowered/reference-data/
 
 Individual schemas are exported as `@portpowered/reference-data/resources/<capability>/configuration.json`, `state-<attribute>.json`, and `message-<name>.json`. Consumers can render field tables directly from these resources. Keep the package imports on the server or at build time to avoid shipping the complete catalog in browser JavaScript.
 
-REST operation guides link directly to `/docs/references/schemas/<name>.json`, `/docs/references/parameters/<name>.json` and `/docs/references/headers/<name>.json`. Schema files use JSON Schema draft-07 with OpenAPI nullability and exclusive bounds converted; parameter/header files retain their OpenAPI definitions. References and discriminator mappings point to the same public host. `/docs/for-ai/schemas.md` and `/docs/references/schemas/index.json` index these files. Agents can retrieve the components needed for one operation without reading the full OpenAPI bundle. Generation checks compile the complete linked schema graph and validate the API's complete request/response examples through it.
+REST operation guides link directly to `/docs/references/schemas/<name>.json`, `/docs/references/parameters/<name>.json` and `/docs/references/headers/<name>.json`. Schema files use JSON Schema draft-07 with OpenAPI nullability and exclusive bounds converted; parameter/header files retain their OpenAPI definitions. References and discriminator mappings point to the same public host. `/docs/for-ai/schemas.md` is a small hub linking alphabetical `/docs/for-ai/schemas/<letter>-<page>.md` shards of at most 40 components. `/docs/references/schemas/index.json` retains the complete machine index. Agents can retrieve the components needed for one operation without reading the full OpenAPI bundle. Generation checks compile the complete linked schema graph and validate the API's complete request/response examples through it.
 
 Run `npm pack` in this directory to produce a portable bundle. The bundle contains generated JSON, the raw public tree and this README; regeneration belongs to the source repository. The Go module embeds that public tree and exposes it through `Files() fs.FS`. Public URLs are rooted at `/llms.txt`, `/docs/for-ai/` and `/docs/references/`; missing files are absent rather than an app-shell fallback. Run `node scripts/validate-public-assets.mjs` and `go test ./...` before release.

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\nStart with [Connect any supported agent](/docs/for-ai/guides/connect-agent.md), or follow these components in order:\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",
+    "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",
     "setupPrompt": null
   },
   {
@@ -80,19 +80,19 @@
   {
     "id": "oauth-consent-and-callback",
     "title": "Obtain user consent and validate the OAuth callback",
-    "content": "# 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\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",
+    "content": "# 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",
     "setupPrompt": null
   },
   {
     "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",
+    "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",
     "setupPrompt": null
   },
   {
     "id": "oauth-token-lifecycle",
     "title": "Exchange, refresh and revoke scoped OAuth tokens",
-    "content": "# 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\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",
+    "content": "# 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",
     "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,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

@@ -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/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/for-ai/schemas/a-1.md

@@ -0,0 +1,44 @@
+# REST components: A, page 1
+
+[Schema directory](/docs/for-ai/schemas.md). Follow only the components linked by your operation.
+
+- [AccessControlEntity](/docs/references/schemas/AccessControlEntity.json) (schemas)
+- [AccessControlOperation](/docs/references/schemas/AccessControlOperation.json) (schemas)
+- [AccessControlRequesterContext](/docs/references/schemas/AccessControlRequesterContext.json) (schemas)
+- [AccessControlResourceContext](/docs/references/schemas/AccessControlResourceContext.json) (schemas)
+- [AccessControlRule](/docs/references/schemas/AccessControlRule.json) (schemas)
+- [AccessControlRuleEffect](/docs/references/schemas/AccessControlRuleEffect.json) (schemas)
+- [AddEndpointGroupMembersRequest](/docs/references/schemas/AddEndpointGroupMembersRequest.json) (schemas)
+- [AirQualitySensorInterfaceAirQualityIndexAttribute](/docs/references/schemas/AirQualitySensorInterfaceAirQualityIndexAttribute.json) (schemas)
+- [AirQualitySensorInterfaceConfiguration](/docs/references/schemas/AirQualitySensorInterfaceConfiguration.json) (schemas)
+- [AirQualitySensorInterfaceGetAirQualityMessage](/docs/references/schemas/AirQualitySensorInterfaceGetAirQualityMessage.json) (schemas)
+- [AirQualityStandard](/docs/references/schemas/AirQualityStandard.json) (schemas)
+- [AlarmInterfaceAlarmStateAttribute](/docs/references/schemas/AlarmInterfaceAlarmStateAttribute.json) (schemas)
+- [AlarmInterfaceConfiguration](/docs/references/schemas/AlarmInterfaceConfiguration.json) (schemas)
+- [AlarmInterfaceRingAlarmMessage](/docs/references/schemas/AlarmInterfaceRingAlarmMessage.json) (schemas)
+- [AlarmInterfaceSilenceAlarmMessage](/docs/references/schemas/AlarmInterfaceSilenceAlarmMessage.json) (schemas)
+- [AlarmInterfaceTestAlarmMessage](/docs/references/schemas/AlarmInterfaceTestAlarmMessage.json) (schemas)
+- [AlarmState](/docs/references/schemas/AlarmState.json) (schemas)
+- [Album](/docs/references/schemas/Album.json) (schemas)
+- [ApiKeySecret](/docs/references/schemas/ApiKeySecret.json) (schemas)
+- [ApplePushNotificationAuthTokenSecret](/docs/references/schemas/ApplePushNotificationAuthTokenSecret.json) (schemas)
+- [ApplePushNotificationPlugin](/docs/references/schemas/ApplePushNotificationPlugin.json) (schemas)
+- [ApplicationInfo](/docs/references/schemas/ApplicationInfo.json) (schemas)
+- [ApplicationInterface](/docs/references/schemas/ApplicationInterface.json) (schemas)
+- [ApplicationInterfaceAttribute](/docs/references/schemas/ApplicationInterfaceAttribute.json) (schemas)
+- [ApplicationInterfaceMessage](/docs/references/schemas/ApplicationInterfaceMessage.json) (schemas)
+- [ApplicationLauncherInterfaceApplicationListAttribute](/docs/references/schemas/ApplicationLauncherInterfaceApplicationListAttribute.json) (schemas)
+- [ApplicationLauncherInterfaceConfiguration](/docs/references/schemas/ApplicationLauncherInterfaceConfiguration.json) (schemas)
+- [ApplicationLauncherInterfaceCurrentApplicationAttribute](/docs/references/schemas/ApplicationLauncherInterfaceCurrentApplicationAttribute.json) (schemas)
+- [ApplicationLauncherInterfaceLaunchApplicationMessage](/docs/references/schemas/ApplicationLauncherInterfaceLaunchApplicationMessage.json) (schemas)
+- [ApplicationLauncherInterfaceStopApplicationMessage](/docs/references/schemas/ApplicationLauncherInterfaceStopApplicationMessage.json) (schemas)
+- [Artist](/docs/references/schemas/Artist.json) (schemas)
+- [AttributeSchema](/docs/references/schemas/AttributeSchema.json) (schemas)
+- [AttributeState](/docs/references/schemas/AttributeState.json) (schemas)
+- [AudioConvertNodeConfiguration](/docs/references/schemas/AudioConvertNodeConfiguration.json) (schemas)
+- [AuthDataType](/docs/references/schemas/AuthDataType.json) (schemas)
+- [AuthLink](/docs/references/schemas/AuthLink.json) (schemas)
+- [AuthLinkSecret](/docs/references/schemas/AuthLinkSecret.json) (schemas)
+- [AuthLinksList](/docs/references/schemas/AuthLinksList.json) (schemas)
+- [AuthorizationInterfaceAuthorizationEstablishedMessage](/docs/references/schemas/AuthorizationInterfaceAuthorizationEstablishedMessage.json) (schemas)
+- [AuthorizationInterfaceAuthorizationUpdateReportMessage](/docs/references/schemas/AuthorizationInterfaceAuthorizationUpdateReportMessage.json) (schemas)

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

@@ -0,0 +1,9 @@
+# REST components: A, page 2
+
+[Schema directory](/docs/for-ai/schemas.md). Follow only the components linked by your operation.
+
+- [AuthorizationInterfaceConfiguration](/docs/references/schemas/AuthorizationInterfaceConfiguration.json) (schemas)
+- [AuthorizationInterfaceRefreshTokensMessage](/docs/references/schemas/AuthorizationInterfaceRefreshTokensMessage.json) (schemas)
+- [AuthorizeDeviceRequest](/docs/references/schemas/AuthorizeDeviceRequest.json) (schemas)
+- [AuthorizeDeviceResponse](/docs/references/schemas/AuthorizeDeviceResponse.json) (schemas)
+- [AuthResourceType](/docs/references/schemas/AuthResourceType.json) (schemas)

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

@@ -0,0 +1,22 @@
+# REST components: B, page 1
+
+[Schema directory](/docs/for-ai/schemas.md). Follow only the components linked by your operation.
+
+- [BarrierControlInterfaceBarrierPositionAttribute](/docs/references/schemas/BarrierControlInterfaceBarrierPositionAttribute.json) (schemas)
+- [BarrierControlInterfaceBarrierStateAttribute](/docs/references/schemas/BarrierControlInterfaceBarrierStateAttribute.json) (schemas)
+- [BarrierControlInterfaceCloseMessage](/docs/references/schemas/BarrierControlInterfaceCloseMessage.json) (schemas)
+- [BarrierControlInterfaceConfiguration](/docs/references/schemas/BarrierControlInterfaceConfiguration.json) (schemas)
+- [BarrierControlInterfaceGoToPositionMessage](/docs/references/schemas/BarrierControlInterfaceGoToPositionMessage.json) (schemas)
+- [BarrierControlInterfaceOpenMessage](/docs/references/schemas/BarrierControlInterfaceOpenMessage.json) (schemas)
+- [BasePlugin](/docs/references/schemas/BasePlugin.json) (schemas)
+- [BaseSecret](/docs/references/schemas/BaseSecret.json) (schemas)
+- [BatchItemError](/docs/references/schemas/BatchItemError.json) (schemas)
+- [BatchMessageItem](/docs/references/schemas/BatchMessageItem.json) (schemas)
+- [BatchOperationRequestId](/docs/references/schemas/BatchOperationRequestId.json) (schemas)
+- [BatchResponseStatus](/docs/references/schemas/BatchResponseStatus.json) (schemas)
+- [BatteryInterfaceBatteryAttribute](/docs/references/schemas/BatteryInterfaceBatteryAttribute.json) (schemas)
+- [BatteryInterfaceConfiguration](/docs/references/schemas/BatteryInterfaceConfiguration.json) (schemas)
+- [BrandingInformation](/docs/references/schemas/BrandingInformation.json) (schemas)
+- [BrightnessInterfaceBrightnessAttribute](/docs/references/schemas/BrightnessInterfaceBrightnessAttribute.json) (schemas)
+- [BrightnessInterfaceConfiguration](/docs/references/schemas/BrightnessInterfaceConfiguration.json) (schemas)
+- [BrightnessInterfaceSetBrightnessMessage](/docs/references/schemas/BrightnessInterfaceSetBrightnessMessage.json) (schemas)