# Connected home requests

Resolve the customer's intended home task and use the existing Port OS connection.
Do this workflow in the current chat without delegation.

For "what's the temperature right now?" with no context distinguishing indoor
temperature from weather, ask whether the customer means indoors or outside.
Do not require a city/ZIP before resolving that distinction. For explicit indoor
requests, discover a thermostat/temperature sensor and read ambient temperature;
a setpoint is not a room measurement. Respect explicit outdoor/weather intent.

Read the task guide index at `references/index.md` and the relevant bundled reference:
temperature, lighting, cameras, rooms, media, battery, find-phone, files or reminders.
These are the same Markdown guides published on the website and exposed as MCP
resources at portos://guides/{topic}. When references are unavailable, read
portos://guides/index with resources/read. The guides explain capability selection,
documented payload fields, verification and operation limits; do not invent commands from product names.

For other device families, read the matching Port OS skill guide at
/docs/for-ai/guides/<guide-id>.md: security (locks, doorbells, security panels),
kitchen (refrigerators, ovens, cooktops, pet feeders), sensors (air quality, humidity, contact,
motion, purifiers), trackers (phone, watch, wallet and laptop trackers),
cloud-drives (iCloud Drive and Photos), model-inference (fal.ai image, speech and
music generation, which can cost money) and reminders-and-calendars. Unlocking a
door, disarming a panel, oven heat, deleting files and paid generation runs need
the customer's confirmation first. Cameras and phone/battery requests keep using
the references above.

Use host-listed account labels to choose the likely authorized home-device
connection. If discovery misses a device, check relevant authorized connections
before denying availability. Keep the returning account with every endpoint,
route and item ID. Ask which account/target before writing when several match.
Do not create connections or expand permissions just to resolve discovery.

For phone/watch battery, charging or Find My requests, inspect every matching
candidate's routes before choosing an exact endpoint. Prefer the concrete device
with an authorized Apple iCloud route for Apple Find My, rather than the first
matching name, an Alexa proxy, a generic plugin or an old unrouted record. If a
same-name record has unavailable data, continue to the relevant route-backed
candidate before claiming iCloud has no reading. Preserve old records; discovery
does not authorize deleting or merging them.

Use declared endpoint_query expansions with forceDeviceAttributeQuery:true for
current state. An observation with error code PROVIDER_NO_STATE means the provider
answered but has no value for that attribute. A STALE reading is the last known state: report it with its sampledAt, not as live or unknown. Errored, missing, invalid or
PROVIDER_NO_STATE readings mean state is
unknown, and a STALE value alone must not support a safety claim such as locked or off. PROVIDER_NO_STATE is not offline: the device may still accept commands, so
send the requested command once and report the outcome as unconfirmed. Only an
UNREACHABLE or ENDPOINT_UNREACHABLE (423) result means offline and a rejected command.
When a chosen device is a simulator, say so, and prefer a real device when both match
(never treat a simulator reading as the household's real state). Inspect camera snapshot pixels before describing a scene. Accepted
control alone does not confirm a physical outcome; verify fresh observations and
do not automatically repeat state changes.

Show what you changed. After a command the customer can see in the device's
card (lights, a thermostat, a robot vacuum), call endpoint_show on each device
you acted on, by its exact endpointId, so the card shows its current state; one
call per device, because a query matching several devices opens only a name
list. Answer in a sentence or two next to the card, and never draw your own card
for it.

For cameras that declare RTC streaming but no on-demand snapshot, prefer the
embedded endpoint_show panel's supported live-view control. Showing a panel does
not establish that video started or that you inspected it. If the host cannot
operate or inspect the embedded viewer, report that limitation. A separate
website may use a different signed-in account; its missing-device result does
not establish that the MCP account lacks the camera.

Explain results and needed clarification in plain customer language. Do not
explain that an internal skill requires a question.

Scopes: a connection can only do what its scopes allow. Reading needs `endpoint:read` and `group:read`, control needs `message:send`, `endpoint_manage` needs `endpoint:write` and `group_manage` needs `group:manage`. On `insufficient_scope` (403) do not retry: ask the customer to reconnect or approve the scope the response names. See the "Scopes for setup" section of the first-setup guide.