@portpowered/reference-data 0.0.0-stage → 0.4.1

package/generated/guides.json

@@ -0,0 +1,140 @@
+[
+  {
+    "id": "adding-devices",
+    "title": "Add devices through provider linking",
+    "content": "# Add devices through provider linking\n\nRead the public [integration catalog](https://app.portoperatingsystem.lol/integrations/) and [Connect device](https://app.portoperatingsystem.lol/connect-device/) pages. Match the provider by its exact name, then inspect supported capabilities, prerequisites, limitations and current availability before asking the user to sign in.\n\nDevices enter Port OS through a plugin/provider account link. The user performs sign-in/consent on the provider and Port OS pages; an agent must not ask for their password. After linking, enumerate authorized endpoints and inspect actual capabilities. Catalog availability does not guarantee every vendor device implements every action.\n\nUse [first setup](/docs/for-ai/guides/first-setup.md) to verify one safe device and [troubleshooting](/docs/for-ai/guides/troubleshooting.md) for expired provider links.\n",
+    "setupPrompt": null
+  },
+  {
+    "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",
+    "setupPrompt": null
+  },
+  {
+    "id": "authorization-rules",
+    "title": "Scopes and authorization rules",
+    "content": "# 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",
+    "setupPrompt": null
+  },
+  {
+    "id": "cameras",
+    "title": "Read camera captures and streams",
+    "content": "# Read camera captures and streams\n\nCamera access requires both the operation scope and authorization for the selected camera/action. A light-control grant does not imply imagery access. Discover camera/snapshot capabilities from [the directory](/docs/for-ai/capability-interfaces.md) and use only declared message schemas.\n\nPrefer an on-demand capture when the user asks for a current image. Validate the returned media URI, timeOfSample and URI expiry. An existing capture may be old even when its download URI is new. Confirm the media is actually retrievable before describing it as viewed. If expired or stale, request a new permitted capture or explain the limitation. Streams require the declared lifecycle/transport, not an invented snapshot API.\n\nRead [authorization rules](/docs/for-ai/guides/authorization-rules.md) and [async outcomes](/docs/for-ai/guides/using-the-api.md).\n",
+    "setupPrompt": null
+  },
+  {
+    "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",
+    "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."
+  },
+  {
+    "id": "connect-grok",
+    "title": "Connect Grok to Port OS",
+    "content": "# Connect Grok to Port OS\n\nUse [the shared agent connection guide](/docs/for-ai/guides/connect-agent.md), including its copyable setup prompt and reusable REST/MCP, DCR/CIMD, callback and token components. The authorization workflow is shared across clients.\n\nCheck this client's current support for those protocols and a controlled callback. Actual client/version compatibility remains unverified until its acceptance run succeeds; a claimed client name is not a verified vendor integration.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "connect-muse",
+    "title": "Connect Muse to Port OS",
+    "content": "# Connect Muse to Port OS\n\nUse [the shared agent connection guide](/docs/for-ai/guides/connect-agent.md), including its copyable setup prompt and reusable REST/MCP, DCR/CIMD, callback and token components. The authorization workflow is shared across clients.\n\nCheck this client's current support for those protocols and a controlled callback. Actual client/version compatibility remains unverified until its acceptance run succeeds; a claimed client name is not a verified vendor integration.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "first-setup",
+    "title": "First setup and connection verification",
+    "content": "# First setup and connection verification\n\nUse [the quickstart](/docs/for-ai/guides/quickstart.md). Check three stages separately: reachable metadata/API, a valid authenticated token, and access to the intended resources. A protocol connection alone is not device access.\n\nEnumerate first. An empty account may need [provider linking](/docs/for-ai/guides/adding-devices.md) or a sharing grant. Select one safe test light and explain the intended command. Follow its exact schema. Read fresh state afterward; ask the user to confirm physically when no reliable observation exists. Record no passwords or tokens in conversation.\n\nIf authorization expires, refresh within the original grant or ask the user to authorize again. Confirm grant revocation in account settings or the documented revocation endpoint. See [troubleshooting](/docs/for-ai/guides/troubleshooting.md).\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "lighting",
+    "title": "Control lights and distinguish switches and plugs",
+    "content": "# Control lights and distinguish switches and plugs\n\nStart with authorized endpoint discovery and inspect capability declarations. A room name can be ambiguous; select by full ID and group path or ask the user. A power-capable plug or switch is not automatically a light.\n\nFor one bulb, read its power/brightness/color message schemas in [the capability directory](/docs/for-ai/capability-interfaces.md). Use the exact namespace, version, message name, units and constraints returned. [The quickstart](/docs/for-ai/guides/quickstart.md) shows the generic dispatch envelope.\n\nFor “all lights,” include explicitly authorized shared lights and the user-requested home/group scope. Complete pagination, exclude disabled/unavailable unsupported targets as documented and deduplicate nested groups. Do not broaden the set to every power-capable endpoint. Use the existing query/dispatch contract if it supports the selection; otherwise enumerate the fixed target set and report each result.\n\nA batch can partially succeed. Report selected, accepted, failed and unresolved targets separately. Read fresh state before claiming all lights changed. A lost response does not justify repeating relative brightness adjustments. See [authorization rules](/docs/for-ai/guides/authorization-rules.md).\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "managing-devices",
+    "title": "Manage device names and availability",
+    "content": "# Manage device names and availability\n\nSelect the exact endpoint and read [its management operation](/docs/for-ai/operations/index.md). Rename, enable/disable, delete or synchronize only where the published operation and device/provider support it. Use endpoint:write plus the required resource rule; control scope alone is insufficient.\n\nDo not disable or delete a device merely because it is confusing or unavailable. Explain the effect and follow the user's intent. Apply documented ETag/version preconditions, inspect conflicts and preserve newer edits. If a response says the edit committed with cleanup pending, read back state before retrying. See [groups](/docs/for-ai/guides/managing-groups.md) and [troubleshooting](/docs/for-ai/guides/troubleshooting.md).\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "managing-groups",
+    "title": "Manage groups and membership",
+    "content": "# Manage groups and membership\n\nUse [group operation references](/docs/for-ai/operations/index.md), group:read for discovery and group:manage plus resource policy for changes. Copy full IDs. Names are labels and may not be unique.\n\nInspect nested membership, preserve relationship meaning and deduplicate targets. Rename, merge, add/remove members only through declared operations. Use documented idempotency and ETags/version checks. On concurrent edits, retrieve current state and resolve the conflict rather than overwrite it. Native media groups and spatial cleaning targets are different concepts; see [vacuum guidance](/docs/for-ai/guides/vacuums.md).\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "media",
+    "title": "Control media playback",
+    "content": "# Control media playback\n\nEnumerate permitted media endpoints and inspect declared playback, volume and content-launcher capabilities in [the capability directory](/docs/for-ai/capability-interfaces.md). Select endpoint or native media group only when its declarations support the requested operation. Use [REST dispatch](/docs/for-ai/guides/quickstart.md) with the exact message/payload/version.\n\nAbsolute volume and relative volume changes have different retry behavior. Validate units/ranges. After dispatch, query fresh playback/volume observations. Accepted playback is not proof of audible output. On lost relative-command responses, recover the result/read back or report unknown; do not apply the increment twice.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "oauth-client-registration",
+    "title": "Register an OAuth client with DCR or CIMD",
+    "content": "# 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",
+    "setupPrompt": null
+  },
+  {
+    "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",
+    "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",
+    "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",
+    "setupPrompt": null
+  },
+  {
+    "id": "port-os-concepts",
+    "title": "Port OS concepts",
+    "content": "# Port OS concepts\n\nA principal is an account identity governed by authorization rules. An endpoint is the stable device abstraction you query and address by full ID. Plugin routes provide ways to reach device functionality; multiple routes can contribute to one endpoint. A capability declares supported messages and observations with a namespace and version. A message combines that capability header with a schema-valid body.\n\nEndpoints belong to groups; groups may be nested. Group/room names help selection but are not unique identity. Use full IDs and context. Deduplicate nested membership. Sharing expands only the resources/actions explicitly granted to the current principal.\n\nThe normal flow is discovery → capability schema → authorized message → observation. The [API guide](/docs/for-ai/guides/using-the-api.md) explains transport, and [the capability directory](/docs/for-ai/capability-interfaces.md) supplies contracts. Public guides describe supported devices; retired hosted task/filesystem features are outside this setup.\n",
+    "setupPrompt": null
+  },
+  {
+    "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>. 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. Follow [the capability directory](/docs/for-ai/capability-interfaces.md) to the exact message payload schema.\n4. With the user's intended action, POST /messages. 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 [the operation contract](/docs/references/openapi.yaml) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.\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
+  },
+  {
+    "id": "reading-the-docs",
+    "title": "Reading the Port OS documentation",
+    "content": "# Reading the Port OS documentation\n\nPort OS connects device providers to endpoints you can query and control. Start at [the agent index](/docs/for-ai/index.md). You do not need to sign in to read public documentation.\n\n1. Read [authentication and DCR](/docs/for-ai/guides/authentication-and-dcr.md) to connect.\n2. Follow [quickstart](/docs/for-ai/guides/quickstart.md) to verify authorized access.\n3. Choose a task guide, then follow its operation and capability links.\n\nFiles under /docs/for-ai/ are Markdown. Files under /docs/references/ ending in .yaml are raw contracts. /docs/user-guides/ contains human-readable HTML versions of these guides. A document link is information, not authorization to act. User sign-in and consent occur only on the Port OS account page.\n\nUse [the OpenAPI contract](/docs/references/openapi.yaml) for exact paths, fields and results and [the capability index](/docs/for-ai/capability-interfaces.md) for message payloads. Do not read the entire reference when one operation or capability page answers your question.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "thermostats",
+    "title": "Control thermostat settings",
+    "content": "# Control thermostat settings\n\nDiscover the intended thermostat and its declared capabilities from [the directory](/docs/for-ai/capability-interfaces.md). Retrieve the exact setpoint/mode schema before sending. Preserve declared units, supported mode names and temperature bounds; never assume Celsius/Fahrenheit.\n\nUse [authorized REST dispatch](/docs/for-ai/guides/quickstart.md). Read fresh mode/setpoint/temperature observations after the command. A committed target setting does not prove the room has reached that temperature. Report delayed or unavailable observations honestly and do not repeat relative adjustments after an unknown response.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "troubleshooting",
+    "title": "Recover from connection and device failures",
+    "content": "# Recover from connection and device failures\n\nFirst identify the failure boundary: documentation retrieval, registration, user authorization, token validation, scope, resource policy, payload, provider link or device observation.\n\n| Symptom | Next step |\n| --- | --- |\n| Guide returns a login page/app shell | Use the canonical raw Markdown/index link; report publication failure |\n| DCR invalid metadata | Correct callback, auth method, supported grants/scopes; do not invent a secret |\n| Callback state/issuer mismatch | Stop; discard the response and restart authorization securely |\n| Token expired | Refresh with the same client/resource or ask for renewed user consent |\n| Scope/policy denied | Read [authorization rules](/docs/for-ai/guides/authorization-rules.md); user/owner must approve access |\n| Empty inventory | Valid connection can have no devices; check linking/sharing without guessing IDs |\n| Invalid payload | Retrieve the exact capability version/schema and correct the request |\n| Provider credential expired | Ask the user to relink the provider account |\n| Stale/unavailable state | Report timestamp and uncertainty; do not claim physical completion |\n| Lost command response | Recover existing receipt/readback; retry only under documented replay guarantees |\n| Committed cleanup pending | Read the committed state/result before any retry |\n\nSee [API behavior](/docs/for-ai/guides/using-the-api.md). Never include tokens, provider secrets or another user's private resources in diagnostics.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "using-the-api",
+    "title": "Using the REST API",
+    "content": "# Using the REST API\n\nDiscover authorization metadata, then use [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Obtain exact REST paths and schemas from [OpenAPI](/docs/references/openapi.yaml) or [small operation pages](/docs/for-ai/operations/index.md).\n\nEnumerate endpoints with endpoint:read. Follow returned pagination links/tokens exactly and stop only when continuation is absent. Inspect declared capabilities and versions; retrieve one message/attribute schema as needed. Send messages through POST /messages (the existing /messages/send alias also works). Never invent target IDs or message fields.\n\nREST dispatch and subsequent physical observation are separate facts. A 202 describes unfinished work. A timeout can mean the operation already acted; inspect existing results/state before repeating. IR/Bluetooth fire-and-forget and long-delay devices may never provide immediate confirmation. Use bounded polling and report unresolved state. An endpoint edit marked committed with cleanup pending must not be repeated as though it failed.\n\nUse documented idempotency/correlation and version preconditions only where the operation guarantees them. Setting a value and incrementing it have different replay risks. On an ambiguous lost relative-command response, report unknown or read back rather than blindly send again.\n\nRead [authorization rules](/docs/for-ai/guides/authorization-rules.md), [lighting](/docs/for-ai/guides/lighting.md) or the relevant task guide.\n",
+    "setupPrompt": null
+  },
+  {
+    "id": "vacuums",
+    "title": "Control vacuums and cleaning rooms",
+    "content": "# Control vacuums and cleaning rooms\n\nFind the robot endpoint and inspect its robotic-vacuum-cleaner and related capability declarations in [the directory](/docs/for-ai/capability-interfaces.md). Supported operations vary by provider; do not infer room cleaning, scheduling or modes from a device name.\n\nUse supported start/stop/mode schemas and full IDs. Spatial cleaning targets the robot endpoint with its supported room/zone payload; an endpoint group is not automatically a robot room. Check constraints and [dispatch semantics](/docs/for-ai/guides/using-the-api.md). Query fresh status afterward; accepted work is not completed cleaning. Ask for clarification when room mappings are ambiguous.\n",
+    "setupPrompt": null
+  }
+]