@somacheck/vibecheck 0.6.10 → 0.6.12

package/recipes/questionpro-research-reflection.md

@@ -0,0 +1,151 @@
+---
+title: QuestionPro + SomaCheck Research Reflection
+recipe_id: questionpro-research-reflection-v1
+status: P1 researcher-private partner-sandbox template
+audience: Researchers evaluating a QuestionPro partnership workflow
+updated: 2026-09-05
+required_mcp_servers:
+  - questionpro-surveybuilder
+  - vibecheck
+---
+
+# QuestionPro + SomaCheck Research Reflection
+
+This recipe helps a researcher privately compare two questionnaire framings and
+produce a copy-ready, non-distributed survey definition. It is not a request for
+the researcher to become a QuestionPro customer or populate a personal account.
+The QuestionPro half is inspected only when a product or integration owner has
+provided a partner-approved sandbox with no participant data.
+
+The researcher holds the phone and is the subject of the proposition. SomaCheck
+returns Aligned or Unaligned plus confidence to the agent as context. The agent
+uses its judgment; the reading is not truth, diagnosis, authorization, evidence
+about a respondent, or a research decision. The researcher remains the authority.
+
+## Experience a partner team can evaluate
+
+The researcher supplies a participant-free survey goal. The agent drafts two
+four-question versions and may offer one SomaCheck check-in on the researcher's
+own preferred direction. The researcher then chooses in words. The output is a
+signal-free survey definition for a QuestionPro owner to review. This recipe
+does not create, publish, distribute, or populate a survey.
+
+## Starter prompt
+
+```text
+Use QuestionPro and SomaCheck to help me prepare a four-question, participant-free
+test-survey plan without changing QuestionPro. I am the researcher and I am
+holding the phone. The survey goal is [GOAL]. Work only from what I provide. If a
+product or integration owner has supplied a preconfigured official QuestionPro
+partner sandbox, you may inspect the focused Survey Builder capability names and
+schemas, but do not call a platform data or action tool. Do not ask me to sign up,
+upgrade, buy a plan, administer access, or populate QuestionPro data. Propose two
+questionnaire framings and show the exact questions. Then offer one short
+first-person proposition about my own preferred direction and wait for my
+acceptance before any proactive SomaCheck ask. Give the result and confidence to
+the agent as context and let it use its judgment. Ask what I choose in words.
+Keep the proposition, reading, confidence, and confirmation out of QuestionPro.
+Return a copy-ready, signal-free survey definition only. Do not create, edit,
+send, distribute, publish, recruit, launch, access responses, or spend anything.
+```
+
+## Prerequisites and partner access
+
+1. The researcher supplies a participant-free goal and holds the linked
+   SomaCheck phone.
+2. QuestionPro or the integration owner supplies a partner-approved sandbox or
+   schema fixture. The recipe never asks the researcher to open or fund an
+   ordinary customer account.
+3. If live discovery is authorized, use only the focused endpoint
+   `https://mcp.questionpro.com/surveybuilder`, not the root, `/all`, or `/full`
+   surface.
+4. Inspect capability names and schemas only. Do not call create, read, send,
+   audience, response, poll, community, employee, or other platform tools.
+5. If no partner sandbox or safe schema fixture exists, label the QuestionPro
+   half untested and still return the copy-ready plan.
+
+## Exact workflow
+
+1. Confirm that the researcher is the phone holder and proposition subject.
+2. Draft two four-question variants using only the supplied brief.
+3. Offer one concise first-person proposition about the researcher's direction.
+4. If the researcher explicitly asks for a vibecheck, use
+   `consent_basis: "user_requested_vibecheck"`. Otherwise wait for acceptance
+   and use `consent_basis: "user_approved_statement"`.
+5. Use one fresh UUID idempotency key and retain the same request handle while
+   pending. Never create a second request to replace an unresolved one.
+6. Give the proposition, Aligned or Unaligned result, and confidence to the
+   agent. Let the agent use its judgment in context without treating the result
+   as authorization or a claim about respondents.
+7. Ask what the researcher chooses in words. Their choice controls the plan.
+8. Return a copy-ready payload with title, purpose, questions, answer choices,
+   and optional logic. Exclude all SomaCheck data and platform identifiers.
+9. Stop before any QuestionPro data or action call. A partner owner may review
+   the payload separately in its own governed workflow.
+
+## Proposition examples
+
+Allowed:
+
+- “I want this survey to focus on first-use clarity.”
+- “This question asks what I am trying to learn.”
+- “I want to separate usability from perceived value.”
+
+Not allowed:
+
+- “Respondents will understand this survey.”
+- “This employee's response proves commitment.”
+- “These answers will be truthful.”
+- “This survey will produce valid data.”
+
+## Visible success condition
+
+The recipe passes when the researcher receives at most one optional check-in,
+states a choice, and receives a four-question, signal-free survey definition.
+No QuestionPro data or action tool runs. Partner integration and distribution
+remain unproven until QuestionPro supplies a sandbox and a documented path that
+another non-Sensie customer can discover, authorize, use, and revoke.
+
+## Failure and degraded paths
+
+- **No partner sandbox:** return the copy-ready plan and label platform
+  interoperability untested. Do not ask the researcher to sign up or upgrade.
+- **Only a broad server is available:** stop rather than connect root, `/all`,
+  `/full`, response, send, audience, community, poll, or employee surfaces.
+- **SomaCheck remains pending:** retain the handle and continue without a result
+  if it expires or is cancelled. Do not create a replacement request.
+- **Unreadable capture:** offer a retry only if the researcher wants one.
+- **The researcher's words differ from the reading:** follow their words.
+
+## Privacy boundary
+
+- Raw motion never reaches QuestionPro or the agent.
+- QuestionPro receives no proposition, reading, confidence, confirmation, or
+  gesture metadata.
+- SomaCheck receives no QuestionPro questions, responses, respondent records,
+  survey IDs, credentials, or hidden fields.
+- No participant-bearing or platform action tool is called.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and proposition subject.
+- [ ] Any QuestionPro surface was supplied by a partner owner, not purchased or
+      populated for this test.
+- [ ] Live access, if present, is limited to schema discovery on the focused
+      `/surveybuilder` endpoint.
+- [ ] No existing responses, analytics, respondents, audiences, employees, or
+      workspace data are retrieved.
+- [ ] One decision creates at most one SomaCheck request.
+- [ ] The agent receives Aligned or Unaligned plus confidence and retains
+      judgment; the researcher retains authority.
+- [ ] The output contains four signal-free questions and no platform write.
+- [ ] No SomaCheck output is written to QuestionPro.
+
+## Sources
+
+- [QuestionPro MCP overview and capability catalog](https://www.questionpro.com/headless/)
+- [QuestionPro MCP connector setup and focused server list](https://www.questionpro.com/help/mcp-help-file.html)
+- [QuestionPro Survey Results tools, excluded from this recipe](https://www.questionpro.com/headless/survey-results/)
+- [QuestionPro LivePolls tools, excluded from this recipe](https://www.questionpro.com/headless/livepolls/)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)

package/recipes/spotify-listening-reflection.md

@@ -0,0 +1,459 @@
+---
+title: Spotify + SomaCheck Listening Reflection
+recipe_id: spotify-listening-reflection-v1
+status: P0 Studio/Kit manual pilot plus MCP fallback; direct attachment gated
+audience: Studio research-preview users (Premium, 18+, select markets, usage limits apply) with a SomaCheck-capable companion agent
+updated: 2026-09-03
+required_mcp_servers:
+  - vibecheck
+partner_paths:
+  - Studio/Kit manual bridge; not an installable MCP server
+  - Spotify first-party Claude integration after capability probe
+  - Reviewed Spotify Web API companion adapter; not a public Spotify MCP server
+---
+
+# Spotify + SomaCheck Listening Reflection
+
+Use this recipe when a person wants Kit in Studio by Spotify Labs to suggest a
+specific track, then wants one private, consented SomaCheck signal before
+deciding whether Kit should play it. The person experiences one complete loop:
+Kit proposes, SomaCheck reflects, the person decides, and—only after a separate
+confirmation—Kit changes playback.
+
+This is a listening-choice reflection, not emotion-aware playback. SomaCheck
+does not report an emotional state, detect a mood, select a track, or authorize
+Spotify. The reading is context for the person. The person remains the
+authority.
+
+## Primary customer experience: Studio/Kit manual pilot
+
+Spotify documents Kit's taste-aware recommendation and playback capabilities,
+but does not document a way to attach SomaCheck MCP to Studio. The currently
+testable Studio experience therefore uses an explicit manual relay through a
+separate SomaCheck-capable agent. This is a real experience test inside Kit,
+but it is **not** a direct MCP integration.
+
+### 1. Ask Kit for one candidate without changing playback
+
+Paste this in Studio:
+
+> Kit, help me choose what to hear next. Suggest one specific track based on my
+> Spotify taste and what is playing, but do not play it, queue it, save it, or
+> change Spotify yet. Show me the exact title and artist. I will take that
+> candidate to SomaCheck. When I return with a result, treat it only as context,
+> not an emotion, instruction, or authorization. Ask me separately whether to
+> play the exact track, and wait for my yes.
+
+If Kit changes playback before the later yes, the test fails. Stop and record
+the premature action; do not continue as though consent worked.
+
+### 2. Ask the SomaCheck-capable companion agent once
+
+Paste the candidate title and artist into an agent with `vibecheck` connected:
+
+> Kit suggested `<track title>` by `<artist>`. Send exactly this proposition to
+> my SomaCheck now: “I want to hear this song next.” Show me the Aligned or
+> Unaligned result and confidence as context only. Do not infer an emotion or
+> tell me what to play.
+
+This is an explicit one-ask request, so the companion uses
+`consent_basis: "user_requested_vibecheck"` and does not ask for redundant
+consent. The exact proposition contains no Spotify account or listening data.
+
+### 3. Relay only the authorized result to Kit, then choose
+
+After seeing the result, paste this in Studio:
+
+> I am choosing to share one SomaCheck result with you for this one decision,
+> knowing this message is processed by Spotify's AI service provider and stored
+> in Studio's local memory: `<Aligned|Unaligned>`. It is a proposition-relative
+> signal, not an emotional state, cause, preference, or authorization. Do not
+> record it, generalize it into my taste, or use it in any podcast, brief, or
+> scheduled task. Now ask me exactly: “Play `<track title>` by `<artist>` now?”
+> Do not change Spotify until I answer.
+
+Kit should ask and stop. Mike then answers yes or no. A yes may cause Kit to
+use its documented built-in playback capability; a no must leave playback
+unchanged. After the test, Mike must ask Kit what it remembers, delete anything
+retained, verify the deletion, and then open a fresh conversation and confirm it
+holds no memory of the track, the verdict, or SomaCheck. Spotify says Studio's
+memory and conversation history can be inspected and deleted locally, while
+messages are processed by an AI service provider and are not used to train that
+provider's models.
+
+### Observable Studio success
+
+- Kit proposes one exact track without changing Spotify.
+- The companion sends exactly one SomaCheck ask.
+- Mike explicitly chooses whether to relay that one result to Kit.
+- Kit names no emotion or cause and makes no automatic track choice from it.
+- Kit asks the exact playback question and waits.
+- Yes plays the named track; no makes no playback change.
+- Studio's memory audit shows nothing retained, or shows it and the deletion is
+  verified in a fresh conversation.
+- The lane is described as a manual Studio bridge with a local context packet,
+  never as a Studio skill, Kit integration, or MCP attachment.
+
+The handoff between Studio and the companion is manual. Do not describe this as
+Kit having called SomaCheck, SomaCheck controlling Spotify, or a deployed
+Spotify MCP integration.
+
+## Official same-agent pilot: Spotify in Claude + SomaCheck
+
+Spotify also publishes a first-party Spotify integration for Claude on web,
+mobile, and desktop. Spotify says it can provide taste-based recommendations,
+preview/save/play results, open them in Spotify, and use Spotify Connect to
+inspect or control devices. This is an official consumer integration, not a
+public Spotify MCP contract and not Studio/Kit.
+
+If one Claude conversation can see both the official Spotify integration and
+the linked SomaCheck remote MCP, Mike can test the complete loop without a
+manual relay or a self-hosted Web API adapter. Run a capability probe first;
+availability in the Claude consumer app does not prove the same tool exists in
+Claude Code or another agent host.
+
+### Exact Claude prompt
+
+> Use my connected Spotify and SomaCheck to help with this listening choice.
+> Send SomaCheck: “I want to hear this song next.” When the result returns,
+> consider the Aligned or Unaligned result and confidence together with the
+> context you already have, then use your judgment to respond and suggest what
+> we might do next. Do not change Spotify until I confirm the action.
+
+The test passes when Claude proposes one Spotify result without acting, makes
+one SomaCheck request, reports the result, waits at the exact playback question,
+and changes Spotify only after a typed yes. A no must create zero Spotify
+mutations. If either integration is missing, stop and use the Studio manual
+pilot or Save to Spotify path; do not substitute an unofficial connector while
+calling it the first-party Claude integration.
+
+For the L44 currently-playing probe, use the exact proposition `I want to turn
+this song up rather than switch to something different.` Give the agent the
+result and confidence and let it use its judgment with the surrounding context.
+Do not prescribe a fixed interpretation or response branch. Probe the connector
+before promising a mutation; if the proposed Spotify action is unavailable,
+say so and leave playback unchanged.
+
+Spotify says both Free and Premium listeners can connect Spotify to Claude,
+with some personalized prompt capabilities differing by plan. Confirm the
+actual playback/device tool before the test. Spotify also says it does not
+share Spotify audio or video content with Anthropic for training.
+
+## Official agent-native wedge: reflect, make a brief, Save to Spotify
+
+Spotify now publishes the `spotify/save-to-spotify` CLI and agent skill for
+Codex, Claude Code, Cursor, OpenClaw, and compatible skill hosts. This is not a
+consumer Web API MCP server and does not attach SomaCheck to Kit, but it is an
+official, immediately installable agent path into a person's Spotify Library.
+
+The customer use case is a private personal audio brief whose direction is hard
+to settle in words. SomaCheck can clarify the person's response to one proposed
+direction. The person then chooses the direction, reviews the script, approves
+the voice engine, and separately approves the Spotify upload. The signal never
+selects, generates, or uploads the episode.
+
+### Exact personal-brief prompt
+
+Use a non-sensitive topic for the first test, such as a public article or a
+short set of notes created specifically for the demo.
+
+> Help me create a three-minute personal talk brief and save it to Spotify, but
+> do not generate audio or upload anything yet. First show two directions: A is
+> direct and action-focused; B is reflective and context-focused. Then send
+> exactly this proposition to my SomaCheck: “I want this brief to be direct and
+> action-focused.” Show the Aligned or Unaligned result and confidence as
+> context only, then ask whether I choose A, B, a revision, or no brief. My typed
+> choice controls. After I choose, draft the complete talk script and show it to
+> me. Ask before sending the script to any voice provider. After I approve the
+> script and voice path, create a local audio file. Show the title, summary,
+> format, duration, and target Spotify show, then ask exactly: “Save this episode
+> to Spotify now?” Do not run any Save to Spotify upload command until I say
+> yes. Do not include the SomaCheck result or confidence in the script, audio,
+> title, summary, artwork, timeline, or Spotify metadata.
+
+### Prerequisites
+
+- Install a reviewed, checksum-verified release from Spotify's official
+  [`spotify/save-to-spotify`](https://github.com/spotify/save-to-spotify)
+  repository and complete its browser login. Do not paste its stored token into
+  chat. As of this review, the latest published release is `v0.2.0`.
+- Use the latest Spotify app and an account with Save to Spotify beta access.
+  Spotify says eligible Free and Premium accounts can use the feature.
+- Provide a supported audio file: `.mp3`, `.m4a`, `.wav`, or `.ogg`.
+- Choose a voice engine separately. The Save to Spotify CLI uploads audio but
+  does not synthesize speech. Prefer local TTS for the first test; obtain
+  separate consent before sending personal source material to a hosted TTS
+  provider.
+- Keep the content primarily spoken-word. Music-first content is not permitted.
+
+### Exact workflow
+
+1. Present two brief directions without invoking SomaCheck or generating audio.
+2. Because the customer prompt explicitly requests it, call
+   `request_vibecheck` once with the exact proposition and
+   `user_requested_vibecheck`.
+3. Report the result as proposition-relative context. Do not map Aligned to A
+   or Unaligned to B.
+4. Ask for a typed choice: A, B, revise, or stop. Stop on silence or stop.
+5. Draft the complete script only after that choice. Clearly mark sourced facts
+   and do not invent material.
+6. Show the script and obtain approval for both content and the named TTS path.
+   A script approval is not upload approval.
+7. Synthesize a local supported audio file and inspect duration/format.
+8. Show the exact episode title, summary, target show, and local file. Ask:
+   `Save this episode to Spotify now?`
+9. Only after a typed yes, invoke the official skill/CLI upload once. Capture
+   the returned episode/library link and readiness status. Do not duplicate an
+   upload after an ambiguous response.
+10. Open the returned link in Spotify and listen. The episode remains private
+    personal content and currently cannot be shared.
+
+### Observable success and failure
+
+Success means one SomaCheck ask, one explicit direction choice, an approved
+talk script, one approved local TTS operation, one separately approved upload,
+and a playable episode in Your Library. The saved episode contains no
+SomaCheck result or claim about the person's state.
+
+If Save to Spotify access is unavailable, content is rejected, processing
+fails, a usage limit is reached, or the audio is not primarily talk, keep the
+local file and report the exact bounded failure. Do not switch to a public
+podcast host, share the content, or repeat the upload without instruction.
+
+Spotify currently documents beta limits of five shows with 30 episodes per
+show for Free and ten shows with 60 episodes per show for Premium. Treat those
+limits as changeable and check the current support page before operational use.
+
+## Automated MCP fallback outside Studio
+
+1. Start any track on an active Spotify device.
+2. In Spotify, choose one candidate next track and copy its Spotify track link.
+3. Give the exact prompt below to an MCP-capable agent that has both SomaCheck
+   and a reviewed Spotify Web API adapter.
+4. Complete the one SomaCheck ask on the phone.
+5. Read the Aligned or Unaligned result and confidence in the agent.
+6. Answer the agent's separate question about whether to queue the named track.
+7. If the answer is yes, see that exact track in the Spotify queue. If the
+   answer is no, Spotify is unchanged.
+
+This fallback is the minimum automatable vertical slice because the effect is visible and
+reversible, the track is chosen by the person, and the Spotify mutation cannot
+happen merely because a reading was Aligned or Unaligned.
+
+## Exact fallback prompt
+
+Replace the placeholder with one Spotify track link. Keep the SomaCheck
+statement exactly as written.
+
+> Use SomaCheck and Spotify together for one listening decision. I am already
+> listening on Spotify. The candidate I chose for next is `<Spotify track
+> link>`. Send exactly this proposition to SomaCheck: “I want this song to be
+> next.” Show me the Aligned or Unaligned result and confidence as context only.
+> Then stop and ask, “Queue `<track title>` by `<artist>` now?” Do not call a
+> Spotify write tool until I answer yes. If I say yes, add only that exact track
+> to my active queue and verify that it appears. If I say no, do nothing. Do not
+> infer my emotion, choose a different track from the result, or save the
+> reading to Spotify.
+
+Because this prompt explicitly requests one SomaCheck, use
+`consent_basis: "user_requested_vibecheck"`; do not ask for redundant consent
+for the phone ask. The later Spotify confirmation is separate and mandatory.
+
+## Prerequisites
+
+1. The person has linked `vibecheck` to their own SomaCheck account and the
+   agent can see `request_vibecheck` and `get_vibecheck_result`.
+2. The agent has a reviewed Spotify connector. Spotify does not publish an
+   official MCP server for the consumer Web API, so inspect the connector's
+   tools and prove that the required operations map to the official endpoints
+   below. Do not treat a community MCP package as Spotify-supported software.
+3. The Spotify app uses Authorization Code with PKCE for a local, desktop, or
+   mobile client, stores tokens outside chat, and requests only
+   `user-read-currently-playing` and `user-modify-playback-state` for this
+   recipe.
+4. The Spotify developer-app owner has Premium. In Development Mode, the
+   current quota documentation limits the app to five allowlisted authenticated
+   users and applies a shared quota distinct from rate limits.
+5. The listener has Premium and an active, non-restricted Spotify Connect
+   device. Start playback manually before the test so queueing has an active
+   target.
+6. The person supplies one exact `open.spotify.com/track/...` link or
+   `spotify:track:...` URI. The adapter converts a link to its exact track URI
+   locally. This P0 path does not ask an agent to search for or recommend music.
+
+Do not paste a Spotify access token, refresh token, client secret, SomaCheck
+link token, or developer credential into the conversation or proposition.
+
+## Required Spotify capability map
+
+Actual MCP tool names vary. Validate behavior against these official Web API
+operations instead of assuming names:
+
+| Purpose | Official operation | Scope | Rule |
+| --- | --- | --- | --- |
+| Resolve the person's exact candidate | `GET /v1/tracks/{id}` | No additional user scope | Read once from the exact supplied track ID; do not search or recommend. |
+| Confirm the active listening context | `GET /v1/me/player/currently-playing` | `user-read-currently-playing` | Read once. A `204`/empty state means the person must start Spotify manually. |
+| Add the person's exact candidate | `POST /v1/me/player/queue?uri={spotify_uri}` | `user-modify-playback-state` | Call only after a post-result yes. A successful `204` means the command was accepted, not that playback changed. |
+| Verify the result | `GET /v1/me/player/queue` | `user-read-currently-playing` or `user-read-playback-state` | Read once and check for the exact URI. Do not continuously poll. |
+
+If the connector lacks queueing, do not silently substitute immediate playback,
+playlist creation, save-to-library, skip, or volume control. Return the exact
+Spotify link so the person can add it manually.
+
+## Exact cross-MCP workflow
+
+Follow these steps in order.
+
+1. **Validate the candidate.** Parse only an exact Spotify track link or URI.
+   Reject playlists, albums, episodes, malformed IDs, and shortened or unknown
+   redirect links for this P0 recipe. Show the resolved track title, artist, and
+   Spotify link with Spotify attribution before any write.
+2. **Read current playback once.** Use the connector operation mapped to
+   `GET /me/player/currently-playing`. State only the literal track and device
+   status. Do not infer energy, mood, stress, or what the listener needs.
+3. **Request one SomaCheck.** Call `request_vibecheck` exactly once with:
+
+   ```json
+   {
+     "statement": "I want this song to be next.",
+     "idempotency_key": "<fresh UUID for this logical ask>",
+     "consent_basis": "user_requested_vibecheck"
+   }
+   ```
+
+   Reuse the same UUID only when retrying the exact same statement after an
+   ambiguous create failure. Never make another ask to seek a preferred result.
+4. **Handle the exact lifecycle.** A terminal `request_vibecheck` response uses
+   `state: "completed"`; a later `get_vibecheck_result` read uses
+   `status: "answered"`. Treat either as the same terminal point. If the
+   initial call is pending, retain its exact `live:<uuid>` handle and perform
+   at most one later `get_vibecheck_result` read. If it is still pending,
+   expired, cancelled, or errors, continue without a result and create no new
+   ask.
+5. **Return the signal without a soundtrack prescription.** Say:
+   `SomaCheck returned <Aligned|Unaligned> at <confidence>. See whether that
+   matches what you notice. It does not tell us why or choose the song.` Keep
+   observation, interpretation, confirmation, and choice distinct.
+6. **Require a new Spotify confirmation.** Ask exactly:
+   `Queue <track title> by <artist> now?` Wait. Aligned is not yes. Unaligned is
+   not no. Silence is not yes. A typed no, decline, correction, or different
+   choice means no Spotify write.
+7. **Queue only after yes.** Add only the exact supplied Spotify track URI. Do
+   not add a recommendation, change playback, skip, change volume, create a
+   playlist, or persist the SomaCheck result.
+8. **Verify once.** Read the queue once and report either that the exact URI is
+   visible or that Spotify accepted the command but the verification did not
+   confirm it. Spotify warns that ordering is not guaranteed when Player API
+   commands are combined, so do not promise that the item will be literally
+   next if other commands or clients changed the queue concurrently.
+
+## What must never cross the boundary
+
+- Raw or batched gyroscope, accelerometer, or magnetometer data.
+- Personal-baseline or calibration data, including any invented
+  `calibration_score` field.
+- A claim such as `report_emotional_state`; the existing SomaCheck MCP emits a
+  proposition-relative Aligned or Unaligned interpretation plus model
+  confidence, not an emotional-state report.
+- The verdict, confidence, confirmation, or inferred meaning in any Spotify
+  URI, query, playlist, description, metadata field, analytics event, or log.
+- Spotify listening data in the SomaCheck proposition. “I want this song to be
+  next” is intentionally self-contained and first-person.
+- Spotify content used to train or fine-tune an AI model. Use minimal metadata
+  transiently for the requested action and follow Spotify's attribution and
+  retention rules.
+
+## Observable success
+
+The test passes only when all of the following are visible:
+
+- Spotify was already playing on the person's active device.
+- The agent displays the exact candidate title, artist, and Spotify link.
+- The phone receives exactly one proposition: “I want this song to be next.”
+- The agent reports one binary reading and confidence without naming an
+  emotion or cause.
+- The agent pauses before a Spotify write and asks for a separate yes/no choice.
+- A typed yes produces one queue-add call for the exact candidate URI.
+- A single queue read shows the exact URI, or the agent truthfully reports that
+  the command was accepted but not verified.
+- A typed no produces zero Spotify writes.
+
+The transcript plus redacted tool names/status codes is the demo receipt. Do
+not record credentials, the raw gesture, or the person's reading in Spotify.
+
+## Failure behavior
+
+- **No Studio/Kit connector:** use this recipe in another MCP-capable agent.
+  Do not call it a Studio integration. A manual copy from that agent into Kit is
+  a manual relay, not a bidirectional MCP demo.
+- **No Spotify queue tool:** show the exact track link and ask the person to add
+  it in Spotify. Do not substitute another mutation.
+- **No active device / empty playback:** ask the person to open Spotify and
+  start a track, then retry only the Spotify read. Do not repeat the SomaCheck.
+- **Restricted device or `401`/`403`:** stop the write, identify whether auth,
+  scope, Premium, allowlist, or device support needs repair, and never request a
+  token in chat.
+- **`429` rate or quota response:** honor `Retry-After` when present. Do not
+  retry in a tight loop. Development quota errors may identify
+  `reason: "QUOTA_EXCEEDED"` and need a later retry rather than backoff alone.
+- **SomaCheck pending, expired, cancelled, unreadable, or error:** do not infer
+  a result and do not create a replacement ask. The person may still decide
+  about Spotify directly.
+- **Candidate mismatch:** do not queue. Show the mismatch and ask the person
+  for a new exact Spotify track link.
+- **Queue verification mismatch:** report uncertainty. Do not enqueue again,
+  because the first `204` may already have mutated the queue.
+
+## Acceptance tests
+
+Run both contract tests and one real-account smoke test before describing the
+recipe as operational.
+
+| Test | Expected result |
+| --- | --- |
+| Explicit request | One `request_vibecheck` call uses `user_requested_vibecheck`; no redundant consent question. |
+| Aligned result | Agent reports context, then stops for Spotify confirmation; zero writes before yes. |
+| Unaligned result | Same stop and confirmation behavior; no automatic calming, grounding, or alternative-track action. |
+| Human says yes | Exactly one queue-add call contains only the supplied URI; one later queue read verifies it. |
+| Human says no or is silent | Zero Spotify writes. |
+| Human overrides signal | The typed choice controls behavior regardless of Aligned or Unaligned. |
+| Pending SomaCheck | Stable `live:<uuid>` is retained; at most one later read; no new request. |
+| Spotify `204`, verification absent | No duplicate write; agent reports accepted but not verified. |
+| Spotify `401`/`403`/restricted device | No fallback mutation and no credential request in chat. |
+| Spotify `429` | Connector honors `Retry-After` and distinguishes shared quota exhaustion when the response supplies that reason. |
+| Payload inspection | No sensor, calibration, proposition result, or confidence appears in Spotify request parameters or logs. |
+| Copy-policy scan | No “emotion detection,” “stress detection,” “your body says,” “calming track,” or authorization language. |
+
+## Launch boundary
+
+The manual Studio pilot is available only to people with access to Spotify's
+research preview. The adapter recipe is suitable for a personal, allowlisted
+Development Mode demo. Neither is approval for public or commercial
+distribution. Spotify's Player API
+pages state that streaming applications may not be commercial, while current
+Extended Quota access requires a qualifying organization and Spotify review.
+Obtain Spotify policy/partner approval and Sensie privacy/legal review before a
+public launch or paid offering.
+
+## Sources
+
+- [Studio by Spotify Labs](https://labs.spotify.com/studio)
+- [How Studio works](https://labs.spotify.com/studio/how-it-works)
+- [Spotify support: How to use Studio](https://support.spotify.com/us/article/studio/)
+- [Studio by Spotify Labs research-preview launch](https://newsroom.spotify.com/2026-05-21/studio-by-spotify-labs-launch/)
+- [Spotify Web API: Building with AI](https://developer.spotify.com/documentation/web-api/tutorials/building-with-ai)
+- [Spotify Web API: Add Item to Playback Queue](https://developer.spotify.com/documentation/web-api/reference/add-to-queue)
+- [Spotify Web API: Get Track](https://developer.spotify.com/documentation/web-api/reference/get-track)
+- [Spotify Web API: Get Currently Playing Track](https://developer.spotify.com/documentation/web-api/reference/get-the-users-currently-playing-track)
+- [Spotify Web API: Get the User's Queue](https://developer.spotify.com/documentation/web-api/reference/get-queue)
+- [Spotify Web API: Authorization Code with PKCE](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)
+- [Spotify Web API: Scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes)
+- [Spotify Web API: Quota modes](https://developer.spotify.com/documentation/web-api/concepts/quota-modes)
+- [Spotify Web API: Rate limits](https://developer.spotify.com/documentation/web-api/concepts/rate-limits)
+- [Spotify's 2024 endpoint-access changes](https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api)
+- [Spotify: Save Your Personal Podcast to Spotify](https://newsroom.spotify.com/2026-05-07/personal-podcasts-launch/)
+- [Spotify Brings Music and Podcast Recommendations to Claude](https://newsroom.spotify.com/2026-04-23/claude-integration/)
+- [Spotify support: Save to Spotify](https://support.spotify.com/us/article/save-to-spotify/)
+- [Official Save to Spotify CLI and agent skill](https://github.com/spotify/save-to-spotify)
+- [SomaCheck setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)