Friction Log

Friction Log

Developer-experience friction met while building Wick on Amazon Devices, Ring, Alexa+ and AWS. 45 entries, each written when the problem was hit, each with the same six fields: the tool, the task, the steps, what the docs led us to expect, what happened, and the workaround and a specific suggestion for the platform.

The full text of every entry is in FRICTION.md. The same problems, gathered by tool with what worked well beside them, are in Product Feedback. This page is the index, and a guide to the ones that shaped the design most.

The ones that shaped Wick

Entry	What was found	What Wick did
FL-022	A Vega app can announce something while another app is in front, but every step of how is undocumented, and two of the documents say it cannot.	Start the app's own service, and post a system toast from it. The door reaches her over anything.
FL-035	Fire TV guidance says no heads-up while another app is in front, and a doorbell is exactly the case it rules out.	The door gets a heads-up; a note never does, and waits quietly in the Notification Center.
FL-027	The Ring Developer Playground delivers no doorbell or motion webhook, so nothing event-driven can be shown on it.	A clearly labelled stand-in doorbell for demo homes.
FL-001	The Alexa+ MCP Toolkit is restricted to select partners, with no application path.	A simulated Alexa+ surface that calls the real MCP server.
FL-015, FL-016, FL-017	Vega's WebView crashes on mount, its player silently refuses cleartext HLS, and an AgentCore Runtime in public network mode gets no outbound UDP.	Ring's live view is bridged from WebRTC to HLS in a container Lambda, served over HTTPS.
FL-013, FL-014, FL-029	The Vega file system never provisions a data root on the virtual device, a service cannot be handed anything, and the card service never launches as a process.	A queue that lives in memory first and writes through to disk only when the disk works, with the app as its one writer.
FL-042	Fire TV's Alexa and Vega's speak different media-session languages for the same words.	A single set of rules for a pause, however it arrives.
FL-024	An MQTT client in a WebSocket cannot authenticate to IoT Core the way MQTT clients are shown to, and the reason is one sentence on one page.	A custom authorizer that takes the device token in the query string.
FL-033	App Runner closes a kept-alive client connection after a few seconds to a minute, and each reconnection is the whole of the "slow" tool call.	Measured and documented; fixing it is tracked in issue 47.
FL-043	Content Personalization takes Watch Activity with a clear log, but where it goes cannot be seen without a catalogue.	Removed the code that fed it, and documented that the integration has no visible effect.
FL-046, FL-047	A Strands TypeScript agent built per request breaks interrupts, sessions and memory; a graph cannot loop back to a node with an outside edge.	Session storage contributed to Amazon's AgentCore SDK, and graphs shaped around the limit.
FL-048	A Bedrock Guardrail on Converse reads the user's question too, and its grounding threshold has to be measured on your own text.	Guardrail applied to the output only, with the threshold measured.

Every entry

	Title
FL-001	Alexa+ MCP Toolkit is restricted to select partners, with no application path
FL-002	"Connect Ring account" in the console reports a link that produces no token
FL-003	Partner-initiated linking leaves the integration dormant until an undocumented-by-placement PATCH
FL-004	Partner-Initiated OAuth 2.0 is documented in full, gated silently, and fails with no error code
FL-005	The "snapshot" endpoint is historical retrieval, and its payload is discoverable only by guessing
FL-006	A missing capability fails as a bare validation error, with nothing naming the capability
FL-007	The Vega SDK ships raw .ts that shadows its own .d.ts, and its strict-types escape hatch is not published
FL-008	Image retrieval fails most first attempts after an event, with an internal error name and no documented settling time
FL-009	SP-5's hardware spike is un-runnable this session, so IoT Core stays unbuilt behind a complete MQTT client
FL-010	FL-003's own documented workaround PATCH is itself rejected, and the console's parallel "Sign in" flow doesn't reach it either
FL-011	First real vega build gets the app packaging correctly; the VVD's own installer then rejects the package with no diagnosable reason
FL-012	A custom Metro resolveRequest silently discarded the Vega SDK's own package-redirection resolver, crashing the app on every single launch
FL-013	IKeplerFileSystem never provisions a data root for this package on the VVD, so every write silently fails and stalls the pairing screen forever
FL-014	Fixing FL-013's symptom exposed the real one: card.service never launches as a process at all, and there is no locally-discoverable manifest field that makes it
FL-015	@amazon-devices/webview 4.0.2 segfaults on mount on the Vega Virtual Device — including Amazon's own vegaWebview template
FL-016	Vega's media player silently refuses a cleartext HLS URL: no request, no error, a black rectangle
FL-017	A Bedrock AgentCore Runtime in PUBLIC network mode gets no outbound UDP, so it cannot receive Ring live video
FL-018	A Vega app without com.amazon.mediatransform.service in its manifest can't decode any video, and nothing says so until playback
FL-019	Ring's only simulator has no chime, so a chime integration can't be demonstrated without buying one
FL-021	useTVEventHandler delivers different key names from the ones HWEvent documents
FL-022	A Vega app can announce something while another app is in front, but every step of how is undocumented, and two of the documents say it cannot
FL-023	The add-on docs name two MCP protocol versions, and only one of them is the one the client is shown sending
FL-024	An MQTT client in a WebSocket cannot authenticate to IoT Core the way MQTT clients are shown to, and the reason is one sentence on one page
FL-025	Fire OS has no emulator, and on the one the FAQ names a television app's remote is silent until something holds focus
FL-026	A Vega service whose start takes longer than eight seconds is killed as "not responding", and nothing in the package says a start has a time limit
FL-027	The Ring Developer Playground delivers no doorbell or motion webhook, so nothing event-driven can be shown on it
FL-028	On Fire OS a short key press reaches JavaScript as a key-up only, and a held key under another name, and neither is said anywhere
FL-029	A Vega app can start its own service, but cannot hand it anything: no launch data, no shared storage, no second message
FL-030	Amazon's own image models on Bedrock are past end of life, and the model list says nothing until you call one
FL-031	Vega Media Controls: once a session is registered the remote's Play/Pause reaches the app twice, the simulator has no way to send a media command, and two ordinary state shapes fail with errors that name neither field
FL-032	Speech to text from a browser through App Runner has to be one buffered POST: App Runner has no WebSockets, says so only in a closed GitHub issue, and documents no request-body limit
FL-033	App Runner's front end closes a kept-alive client connection after a few seconds to a minute, says why nowhere, and each reconnection is the whole of the "slow" tool call
FL-035	Fire TV's notification guidance says "no heads-up while another app is in front" in a blog post, says nothing of foreground services, and a doorbell is exactly the case it rules out
FL-036	The Android TV emulator draws no notification of a third-party app: not as a heads-up, not in its notifications panel
FL-038	Vega answers whether high-contrast text is on, but says nothing an app can use about text size, and the simulator cannot turn either setting, or VoiceView, on
FL-040	The Alexa+ MCP add-on design guide names Card, List and Carousel but gives none of them an anatomy, and its components page is not in its own navigation
FL-041	Ring signs a webhook's body and nothing else, documents no replay window, and does not say whether a retry is stamped afresh
FL-042	Fire TV's Alexa and Vega's speak different media-session languages for the same words, and nothing that runs off a Fire TV can send either
FL-043	Content Personalization takes Watch Activity with a clear log, but where it goes cannot be seen without a catalogue
FL-044	Vega's only documented toast API is a React hook, and the one place a toast is needed has no React tree
FL-045	A Step Functions Wait takes a moment, but a task's timeout only takes seconds from now
FL-046	A Strands agent built per request: interrupts, sessions and memory each assume one long-lived agent
FL-047	A Strands TypeScript Graph cannot loop back to a node that has an edge from outside the loop
FL-048	A Bedrock Guardrail on Converse reads the user's question too, and its grounding threshold has to be measured on your own text
FL-049	Amazon Device Messaging is the documented way to reach a Fire TV app from a server, on Fire OS and on Vega, and Wick does not use it yet