@somacheck/vibecheck 0.6.10 → 0.6.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sensie LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,7 +9,7 @@ Your agent has your context. It does not have your gut. This is the bridge.
 
 Fair. Here is what you need, without executing anything.
 
-**What the `link` command does.** `npx -y @somacheck/vibecheck@0.6.10 link <CODE> --client <CLIENT>`
+**What the `link` command does.** `npx -y @somacheck/vibecheck@0.6.11 link <CODE> --client <CLIENT>`
 exchanges a short-lived pairing code, generated inside the SomaCheck iOS app, for
 a bearer token. It writes that token to `~/.sensie/config.json` with mode `0600`,
 offers to configure supported agent clients found on the computer, and checks the
@@ -97,9 +97,9 @@ before the pairing code is redeemed.
 To configure or repair a client later:
 
 ```text
-npx -y @somacheck/vibecheck@0.6.10 setup codex
-npx -y @somacheck/vibecheck@0.6.10 setup claude
-npx -y @somacheck/vibecheck@0.6.10 doctor
+npx -y @somacheck/vibecheck@0.6.11 setup codex
+npx -y @somacheck/vibecheck@0.6.11 setup claude
+npx -y @somacheck/vibecheck@0.6.11 doctor
 ```
 
 Manual registration remains available:
@@ -109,13 +109,13 @@ Manual registration remains available:
      "mcpServers": {
        "vibecheck": {
          "command": "npx",
-        "args": ["-y", "@somacheck/vibecheck@0.6.10", "serve", "--client", "codex"]
+        "args": ["-y", "@somacheck/vibecheck@0.6.11", "serve", "--client", "codex"]
        }
      }
    }
    ```
 
-   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.6.10 serve --client claude`
+   For Claude Code: `claude mcp add --scope user vibecheck -- npx -y @somacheck/vibecheck@0.6.11 serve --client claude`
 
 The link step writes only the bearer token in `~/.sensie/config.json`. The client
 setup step asks Codex or Claude to add the pinned MCP command to that client's own
@@ -177,6 +177,74 @@ npx skills add Sensie-agents/vibecheck --skill vibecheck
 The skill expects the `@somacheck/vibecheck` MCP server to already be linked as
 `vibecheck`. Installing the skill does not copy or replace the bearer token.
 
+## Agent reflection recipes
+
+Give your agent a consented signal when words are the bottleneck. These recipes
+combine SomaCheck with a named platform so a person can privately reflect on
+their own wording, interpretation, study design, or listening choice:
+
+- [Typeform + SomaCheck](recipes/typeform-research-reflection.md)
+- [Dovetail + SomaCheck](recipes/dovetail-research-reflection.md)
+- [Prolific + SomaCheck](recipes/prolific-research-reflection.md)
+- [Maze + SomaCheck](recipes/maze-research-reflection.md)
+- [Chattermill + SomaCheck](recipes/chattermill-research-reflection.md)
+- [User Interviews + SomaCheck](recipes/user-interviews-research-reflection.md)
+- [Sprig + SomaCheck](recipes/sprig-research-reflection.md)
+- [Great Question + SomaCheck](recipes/great-question-research-reflection.md)
+- [QuestionPro + SomaCheck](recipes/questionpro-research-reflection.md)
+- [Spotify manual Studio/Kit bridge + SomaCheck](recipes/spotify-listening-reflection.md)
+
+The research recipes are researcher-private, and the Spotify recipe is
+listener-private. They do not assess respondents, participants, creators, or
+other listeners; export individual readings; authorize platform changes; or use
+SomaCheck for quality, truthfulness, eligibility, payment, employment, ranking,
+or research validity. A reading is context for the phone holder's next choice;
+the person remains the authority.
+
+List the packaged experiences without connecting to either MCP server:
+
+```text
+npx -y @somacheck/vibecheck recipes
+```
+
+Print one experience's prerequisites, success condition, and exact starter
+prompt:
+
+```text
+npx -y @somacheck/vibecheck recipe typeform-research-reflection-v1
+npx -y @somacheck/vibecheck recipe dovetail-research-reflection-v1
+npx -y @somacheck/vibecheck recipe prolific-research-reflection-v1
+npx -y @somacheck/vibecheck recipe user-interviews-research-reflection-v1
+```
+
+Print only a copyable starter prompt for the read-only direct-MCP tests:
+
+```text
+npx -y @somacheck/vibecheck recipes --id maze-research-reflection-v1 --format prompt
+npx -y @somacheck/vibecheck recipes --id chattermill-research-reflection-v1 --format prompt
+npx -y @somacheck/vibecheck recipes --id user-interviews-research-reflection-v1 --format prompt
+```
+
+These commands only print guides. They do not install, connect, or authorize a
+partner MCP server, call either MCP, or change partner-platform state. In every
+recipe, the phone holder is the person reflecting on their own choice.
+
+### Private Studio pilot packet
+
+[`recipes/studio-somacheck-context.md`](recipes/studio-somacheck-context.md) is
+a reviewed, paste-only context packet for a private Studio by Spotify Labs
+research-preview pilot. It is deliberately absent from `vibecheck recipes`: it
+is not a connected or live recipe, a Studio skill, a Kit plugin, or native MCP.
+Review the packet and run its focused contract test before any pilot:
+
+```text
+node --import tsx --test test/studio-context-packet.test.ts
+```
+
+Run that command from `packages/vibecheck` after `npm install`. Do not grant
+Studio access to this repository or another directory. File access remains
+blocked until the capability and revocation probe in the safety review passes.
+
 ## Tools
 
 | Tool | What it does |
@@ -223,7 +291,9 @@ pending response without that hook (including the hosted connector, which is
 stateless per request and never arms the watch) tells the agent the exact
 `request_id` and the person's expiry, and to call `get_vibecheck_result` again
 in about 15 seconds, repeating at that cadence until the state is answered or
-expired.
+expired without ending the turn or asking the person whether to check. A
+still-pending read of the same Live Ask repeats that instruction; the read does
+not invent an expiry because the result endpoint does not return one.
 
 The 45-second whole-call deadline also covers the one create request. If that
 network request is aborted after an ambiguous commit, retry the exact same

package/claude-marketplace/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "vibecheck",
       "source": "./plugins/vibecheck",
       "description": "Let Claude offer a vibecheck and continue when the phone result arrives.",
-      "version": "0.6.10",
+      "version": "0.6.11",
       "author": {
         "name": "Sensie",
         "email": "agents@joinsensie.com"

package/claude-marketplace/plugins/vibecheck/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "vibecheck",
   "description": "Let Claude offer a SomaCheck vibecheck and continue when the phone result arrives.",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "author": {
     "name": "Sensie",
     "email": "agents@joinsensie.com"
   },
-  "homepage": "https://github.com/sensie-app/Somacheck/tree/main/packages/vibecheck",
-  "repository": "https://github.com/sensie-app/Somacheck",
-  "license": "UNLICENSED",
+  "homepage": "https://github.com/Sensie-agents/vibecheck",
+  "repository": "https://github.com/Sensie-agents/vibecheck",
+  "license": "MIT",
   "keywords": ["vibecheck", "somacheck", "decision-support", "mcp"]
 }

package/claude-marketplace/plugins/vibecheck/hooks/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx -y @somacheck/vibecheck@0.6.10 claude-hook await-result",
+            "command": "npx -y @somacheck/vibecheck@0.6.11 claude-hook await-result",
             "asyncRewake": true,
             "timeout": 900
           }

package/dist/cli.js

@@ -10,6 +10,7 @@ import { awaitClaudeVibecheckResult } from "./claude-hook.js";
 import { PACKAGE_SPEC, SUPABASE_PUBLISHABLE_KEY, SUPABASE_URL } from "./constants.js";
 import { LinkPersistenceError, NonInteractiveLinkError, linkAgent } from "./link.js";
 import { checkReadiness } from "./readiness.js";
+import { formatRecipeDetail, formatRecipeList, formatRecipePrompt, getRecipeExperience } from "./recipes.js";
 import { createVibecheckServer } from "./server.js";
 const api = new SupabaseAgentApi(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY);
 const runner = new LocalCommandRunner();
@@ -26,6 +27,9 @@ function usage() {
         "  npx -y @somacheck/vibecheck link <CODE> [--client codex|claude|all|none]",
         "  npx -y @somacheck/vibecheck setup <codex|claude|all>",
         "  npx -y @somacheck/vibecheck doctor",
+        "  npx -y @somacheck/vibecheck recipes",
+        "  npx -y @somacheck/vibecheck recipes --id <id> --format prompt",
+        "  npx -y @somacheck/vibecheck recipe <id>",
     ].join("\n");
 }
 function parseLinkClient(args) {
@@ -228,6 +232,33 @@ async function main() {
     if (args.length === 2 && args[0] === "claude-hook" && args[1] === "await-result") {
         return runClaudeResultHook();
     }
+    if (args[0] === "recipes") {
+        if (args.length === 1) {
+            output(formatRecipeList());
+            return 0;
+        }
+        if (args.length === 5 && args[1] === "--id" && args[3] === "--format" && args[4] === "prompt") {
+            const recipe = getRecipeExperience(args[2]);
+            if (recipe === null) {
+                process.stderr.write(`Unknown recipe ID.\n\n${formatRecipeList()}\n`);
+                return 1;
+            }
+            output(formatRecipePrompt(recipe));
+            return 0;
+        }
+        throw new Error(usage());
+    }
+    if (args[0] === "recipe") {
+        if (args.length !== 2)
+            throw new Error(usage());
+        const recipe = getRecipeExperience(args[1]);
+        if (recipe === null) {
+            process.stderr.write(`Unknown recipe ID.\n\n${formatRecipeList()}\n`);
+            return 1;
+        }
+        output(formatRecipeDetail(recipe));
+        return 0;
+    }
     if (args[0] === "link") {
         if (args.length < 2)
             throw new Error(usage());

package/dist/constants.js

@@ -2,8 +2,9 @@
 export const SUPABASE_URL = "https://pbldcmniommltbdwuykk.supabase.co";
 export const SUPABASE_PUBLISHABLE_KEY = "sb_publishable_af-lUNI2FqEcb-oGy-4uxQ_cnm6kY85";
 export const PACKAGE_NAME = "@somacheck/vibecheck";
-export const PACKAGE_VERSION = "0.6.10";
+export const PACKAGE_VERSION = "0.6.11";
 export const PACKAGE_SPEC = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
+export const SOMACHECK_SETUP_URL = "https://testflight.apple.com/join/C4mAH3zz";
 export const MCP_SERVER_NAME = "vibecheck";
 export const LEGACY_HOSTED_MCP_SERVER_NAME = "somacheck";
 export const BACKEND_PROTOCOL_VERSION = 5;

package/dist/readiness.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { readConfig } from "./config.js";
 import { SomaCheckCompatibilityError, SomaCheckHttpError } from "./api.js";
 import { clientDisplayName, clientRegistrationState, detectLegacyHostedRegistration, isClientInstalled, manualLegacyHostedRemoveCommand, manualRemoveCommand, manualSetupCommand, } from "./client-setup.js";
-import { BACKEND_PROTOCOL_VERSION, PACKAGE_VERSION } from "./constants.js";
+import { BACKEND_PROTOCOL_VERSION, PACKAGE_VERSION, SOMACHECK_SETUP_URL } from "./constants.js";
 function vibecheckRegistrationCount(value) {
     if (!value || typeof value !== "object")
         return 0;
@@ -32,7 +32,7 @@ export async function checkReadiness(dependencies) {
     }
     catch {
         dependencies.output("✗ This computer is not linked to SomaCheck.");
-        dependencies.output("  Install SomaCheck from the current TestFlight invitation: https://testflight.apple.com/join/C4mAH3zz");
+        dependencies.output(`  Install SomaCheck from the current TestFlight invitation: ${SOMACHECK_SETUP_URL}`);
         dependencies.output("  Then open SomaCheck → Settings → Agent → Connect your agent and run the command shown there.");
         return {
             linked: false,

package/dist/recipes.js

@@ -0,0 +1,191 @@
+export const RECIPE_CATALOG = [
+    {
+        id: "typeform-research-reflection-v1",
+        title: "Typeform + SomaCheck Research Reflection",
+        guidePath: "recipes/typeform-research-reflection.md",
+        purpose: "Privately reflect on the researcher's own Typeform wording, structure, or launch readiness.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own work, never a respondent or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The researcher has separately connected and authorized Typeform MCP for the correct account and data region; this command does not connect or authorize it.",
+            "The researcher can name one researcher-authored form, draft, or aggregate analytics view that does not require respondent rows, contacts, identifiers, or free-text answers.",
+        ],
+        starterPrompt: "Review the researcher-authored structure of my Typeform [FORM NAME OR ID] using only form structure, logic, and aggregate analytics—never respondent-level rows, contacts, identifiers, or free-text answers. Then help me privately reflect on my own wording or readiness with one optional SomaCheck vibecheck. If you propose a vibecheck, show me the exact first-person proposition and wait for my acceptance. Treat Aligned or Unaligned plus confidence as context, not truth or authorization. Do not write the reading to Typeform, and stop before any Typeform edit or publication until I separately approve the exact change.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and chooses the next step; no respondent data or SomaCheck result enters Typeform, and no Typeform state changes without separate explicit approval.",
+    },
+    {
+        id: "dovetail-research-reflection-v1",
+        title: "Dovetail + SomaCheck Research Reflection",
+        guidePath: "recipes/dovetail-research-reflection.md",
+        purpose: "Privately reflect on the researcher's own Dovetail planning document or evidence interpretation.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own work, never a participant or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The researcher has separately connected and authorized Dovetail MCP for the intended workspace; this command does not connect or authorize it.",
+            "The researcher can name one researcher-authored, participant-free Dovetail brief, guide, plan, or de-identified synthesis.",
+        ],
+        starterPrompt: "Review only my researcher-authored Dovetail doc [DOC TITLE OR ID]. Do not open raw interviews, transcripts, recordings, highlights, contacts, identifiers, participant responses, or any broader workspace content. Separate what the document says from what you infer, then help me privately reflect on my own interpretation or next step with one optional SomaCheck vibecheck. If you propose a vibecheck, show me the exact first-person proposition and wait for my acceptance. Treat Aligned or Unaligned plus confidence as context, not truth or authorization. Keep the reading out of Dovetail, and do not create a comment or make another Dovetail change unless I separately approve its exact signal-free content.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and chooses the next step; no participant material or SomaCheck result enters the cross-MCP flow, and Dovetail changes require separate explicit approval.",
+    },
+    {
+        id: "prolific-research-reflection-v1",
+        title: "Prolific + SomaCheck Research Reflection",
+        guidePath: "recipes/prolific-research-reflection.md",
+        purpose: "Privately reflect on the researcher's own Prolific study or recruitment plan before formal review.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own work, never a participant or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The researcher has separately installed, reviewed, pinned, and authorized the official Prolific MCP server; this command does not install, connect, or authorize it.",
+            "The researcher can name one researcher-owned workspace, project, or draft study without retrieving submissions, messages, participant identifiers, responses, or demographic exports.",
+        ],
+        starterPrompt: "Review my researcher-owned Prolific [WORKSPACE, PROJECT, OR DRAFT STUDY NAME OR ID] using only minimum study-planning information. Do not retrieve participant-level data or use a SomaCheck result for recruitment, filtering, eligibility, payment, quality, authenticity, or performance. Separate the study facts from your inferences, then help me privately reflect on my own plan or readiness with one optional SomaCheck vibecheck. If you propose a vibecheck, show me the exact first-person proposition and wait for my acceptance. Treat Aligned or Unaligned plus confidence as context, not truth or authorization. Do not create filters or studies, publish, spend money, or write the reading to Prolific.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and chooses the next step; no participant data or SomaCheck result enters Prolific, and the recipe creates no filter, study, publication, or spend.",
+    },
+    {
+        id: "maze-research-reflection-v1",
+        title: "Maze + SomaCheck Research Reflection",
+        guidePath: "recipes/maze-research-reflection.md",
+        purpose: "Privately reflect on the researcher's interpretation of one Maze study using metadata or one aggregate summary, with no Maze mutation.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own interpretation plan, never a participant, respondent, tester, or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The product or integration owner has provisioned an organization-authorized Maze connection or partner sandbox at https://connect.maze.co/mcp; running this recipe does not ask the researcher to sign up, upgrade, administer access, or populate Maze data.",
+            "The provisioned workspace supplies one named existing study with safe metadata or an aggregate summary; if it does not, the Maze half remains untested and the researcher still receives a copy-ready plan.",
+        ],
+        starterPrompt: "Use Maze and SomaCheck to help me reflect on my own interpretation plan for one named Maze study. I am the researcher and I am holding the phone. The study is [STUDY NAME OR ID PROVIDED BY THE WORKSPACE OWNER]. Use only the preconfigured official hosted read-only Maze MCP at https://connect.maze.co/mcp. Read only that study's safe metadata or one aggregate summary. Do not retrieve transcripts, recordings, heatmaps, click maps, mission answers, participant identifiers, contact fields, demographic exports, free text, or row-level data. Label what Maze literally reports separately from your interpretation, then offer two defensible framings. Offer one short first-person proposition about my own interpretation plan and wait for my acceptance before any proactive SomaCheck ask. Treat Aligned or Unaligned plus confidence as context, not truth, diagnosis, authorization, or evidence about a participant. Ask what I choose in words. Keep the proposition, reading, confidence, and confirmation out of Maze. Do not create, edit, publish, delete, archive, export, share, tag, comment, or otherwise write to Maze. If the preconfigured connection or a safe runtime read is absent, label the Maze half untested, return a copy-ready interpretation plan, and tell the integration owner what capability is missing. Do not ask me to sign up, upgrade, administer access, or populate Maze data.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and states a typed choice after a real metadata or aggregate read from a preconfigured workspace; no participant data or SomaCheck output enters Maze, and the Maze workspace remains unchanged.",
+    },
+    {
+        id: "chattermill-research-reflection-v1",
+        title: "Chattermill + SomaCheck Research Reflection",
+        guidePath: "recipes/chattermill-research-reflection.md",
+        purpose: "Privately reflect on aggregate Chattermill metrics or generated highlights while excluding individual feedback and every write path.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own interpretation, never a customer, respondent, participant, or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The product or integration owner has provisioned an organization-authorized Chattermill connection or partner sandbox at https://app.chattermill.com/mcp with mcp:read; running this recipe does not ask the researcher to sign up, purchase access, administer access, or populate Chattermill data.",
+            "The provisioned workspace supplies one named existing project for which get_metrics or generate_highlights is sufficient; get_feedback, search_observations, identifier-bearing attributes, and free text remain prohibited.",
+        ],
+        starterPrompt: "Use Chattermill and SomaCheck to help me reflect on my own interpretation of one named project's customer-feedback insights. I am the researcher and I am holding the phone. The project is [PROJECT NAME OR ID PROVIDED BY THE WORKSPACE OWNER]. Use only the preconfigured official hosted read-only Chattermill MCP at https://app.chattermill.com/mcp. Read only aggregate metrics with get_metrics or generated highlights with generate_highlights, plus the minimum discovery metadata needed to build that query. Never call get_feedback or search_observations, enumerate identifier-bearing attributes, or surface individual feedback, source quotes, respondent identifiers, contact fields, or free text. Label what the aggregate output literally reports separately from your interpretation, then offer two defensible interpretations. Offer one short first-person proposition about my own interpretation or next step and wait for my acceptance before any proactive SomaCheck ask. Treat Aligned or Unaligned plus confidence as context, not truth, diagnosis, authorization, or evidence about an individual customer. Ask what I choose in words. Keep the proposition, reading, confidence, and confirmation out of Chattermill. Do not create, edit, publish, delete, share, export, tag, comment, or otherwise write to Chattermill. If the preconfigured connection, mcp:read, or a safe aggregate runtime tool is absent, label the Chattermill half untested, return a copy-ready interpretation, and tell the integration owner what capability is missing. Do not ask me to sign up, purchase access, administer access, or populate Chattermill data.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and states a typed choice after a real aggregate or generated-summary read from a preconfigured workspace; no individual feedback or SomaCheck output enters the cross-MCP flow, and Chattermill remains unchanged.",
+    },
+    {
+        id: "user-interviews-research-reflection-v1",
+        title: "User Interviews + SomaCheck Research Reflection",
+        guidePath: "recipes/user-interviews-research-reflection.md",
+        purpose: "Privately reflect on the researcher's own User Interviews study framing and produce a copy-ready test-project plan without calling a platform mutation.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own study direction, never a respondent, participant, candidate, or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The planning workflow requires no User Interviews account or connector because it calls no platform data or action tool.",
+            "For partner integration validation only, the product or integration owner may supply a preconfigured partner sandbox whose runtime capability list can be inspected without invoking a project, recruitment, participant-data, contact, publication, or spend tool; the researcher is never asked to request access or populate platform data.",
+        ],
+        starterPrompt: "Use User Interviews and SomaCheck to help me prepare one clearly named, participant-free test-project plan without changing User Interviews. I am the researcher and I am holding the phone. The study idea is [STUDY IDEA]. Work only from what I provide here. If a product or integration owner has supplied a preconfigured official User Interviews partner sandbox, you may inspect its capability names and schemas, but do not call any platform data or action tool. The planning workflow does not require me to sign up, request access, purchase a plan, or populate User Interviews data. Do not retrieve candidates, participants, screeners, responses, profiles, identifiers, messages, recordings, transcripts, session data, or other workspace data. Propose two neutral study framings and show the exact signal-free project copy. Then offer one short first-person proposition about my own preferred direction and wait for my acceptance before any proactive SomaCheck ask. Treat Aligned or Unaligned plus confidence as context, not truth, diagnosis, authorization, or evidence about another person. Ask what I choose in words. Keep the proposition, reading, confidence, and confirmation out of User Interviews. Return a copy-ready project payload only. Do not create, edit, recruit, invite, message, schedule, screen, launch, publish, attach incentives, spend, read participant data, or call a broader or undocumented tool.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition and states a typed choice; the agent returns a copy-ready signal-free test-project plan, invokes no User Interviews data or action tool, and performs no recruitment, participant read, contact, mutation, launch, publication, incentive, payment, or spend.",
+    },
+    {
+        id: "sprig-research-reflection-v1",
+        title: "Sprig + SomaCheck Research Reflection",
+        guidePath: "recipes/sprig-research-reflection.md",
+        purpose: "Privately reflect on an owner-supplied, participant-free Sprig test artifact and return a copy-ready revision without changing Sprig.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own study direction, never a respondent or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The product or integration owner has provisioned an organization-authorized Sprig connection or partner sandbox; this workflow does not ask the researcher to sign up, upgrade, purchase access, administer access, or populate Sprig data.",
+            "The owner supplies one clearly named, participant-free test artifact and a least-privilege runtime tool that can read only the artifact metadata and question text needed for the review.",
+        ],
+        starterPrompt: "Use Sprig and SomaCheck to help me privately reflect on one participant-free test artifact supplied by the product or integration owner. I am the researcher and I am holding the phone. The artifact is [TEST ARTIFACT NAME OR ID PROVIDED BY THE OWNER]. Use only the preconfigured Sprig partner sandbox or organization-authorized connection. Read only the minimum artifact metadata and question text needed for this review. Do not retrieve responses, themes, source quotes, respondent fields, identifiers, contact data, or PII. Offer two defensible wording directions, then offer one short first-person proposition about my own direction and wait for my acceptance before any proactive SomaCheck ask. After the check, use only the proposition, Aligned or Unaligned, and confidence together with our conversation context; exercise your judgment about the next conversational move and do not apply a fixed script to either result. I decide what the signal means and what happens next. Keep the proposition, reading, confidence, and confirmation out of Sprig. Return a copy-ready, signal-free revision only. Do not create, edit, publish, delete, share, archive, export, duplicate, target, distribute, launch, contact anyone, or otherwise write to Sprig. If the preconfigured connection or safe read tool is absent, label the Sprig half untested, work only from a participant-free brief I provide, and tell the integration owner what capability is missing. Do not ask me to sign up, upgrade, purchase access, administer access, or populate Sprig data.",
+        successCondition: "The researcher receives at most one optional signal about their own proposition, the agent retains judgment about the next conversational move, and the researcher receives a copy-ready signal-free revision after a narrow read of an owner-supplied participant-free test artifact; no research data or SomaCheck output crosses systems, and Sprig remains unchanged.",
+    },
+    {
+        id: "great-question-research-reflection-v1",
+        title: "Great Question + SomaCheck Research Reflection",
+        guidePath: "recipes/great-question-research-reflection.md",
+        purpose: "Privately reflect on a survey framing using one owner-provisioned, participant-free Great Question test artifact without changing Great Question.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own study framing, never a candidate, participant, or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "The product or integration owner has provisioned an organization-authorized Great Question connection or partner sandbox at https://greatquestion.co/api/mcp/v1 with PII hiding enabled; running this recipe does not ask the researcher to sign up, upgrade, purchase, administer access, or populate Great Question data.",
+            "The owner supplies one participant-free test study, and the client restricts the platform half to get_survey_study for that exact artifact; no discovery or mutation tool is approved.",
+        ],
+        starterPrompt: "Use Great Question and SomaCheck to help me reflect on a five-question test survey plan without changing Great Question. I am the researcher and I am holding the phone. The product or integration owner has provisioned a partner sandbox and named this participant-free test study: [TEST STUDY NAME OR ID]. Read only that study's safe title, purpose, and question structure with get_survey_study. Do not search or list the workspace, and do not read candidates, participants, screeners, responses, sessions, transcripts, recordings, highlights, insights, reels, or other workspace data. Propose two neutral study framings and show their exact questions. Then offer one short first-person proposition about my own preferred framing and wait for my acceptance before any proactive SomaCheck ask. Give the agent the Aligned or Unaligned result plus confidence as context and let it use that context with its judgment. Ask what I choose in words. Keep the proposition, reading, confidence, and my confirmation out of Great Question. Return a signal-free, copy-ready research plan only. Do not create, update, delete, recruit, invite, message, schedule, incentivize, launch, publish, or otherwise write to Great Question. Do not ask me to sign up, upgrade, purchase, administer access, or populate Great Question data.",
+        successCondition: "The researcher receives at most one optional signal, states a choice, and receives a copy-ready five-question plan; only get_survey_study reads the exact owner-supplied test artifact, Great Question remains unchanged, and no recruitment or participant data is accessed.",
+    },
+    {
+        id: "questionpro-research-reflection-v1",
+        title: "QuestionPro + SomaCheck Research Reflection",
+        guidePath: "recipes/questionpro-research-reflection.md",
+        purpose: "Privately compare questionnaire wording and return a copy-ready, non-distributed survey plan for a partner-owned evaluation.",
+        phoneHolder: "The phone holder is the researcher reflecting on their own questionnaire wording, never a respondent, audience member, or employee.",
+        prerequisites: [
+            "SomaCheck is ready on the researcher's iPhone and the vibecheck MCP is linked to that researcher's agent client.",
+            "A QuestionPro or integration owner supplies a partner-approved sandbox or schema fixture; the researcher is not asked to sign up, upgrade, or populate vendor data.",
+            "Any live discovery is limited to schemas at https://mcp.questionpro.com/surveybuilder, never a root or all-tools endpoint.",
+        ],
+        starterPrompt: "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 goal is [GOAL]. Work only from what I provide. If a product or integration owner supplied a preconfigured official QuestionPro partner sandbox, inspect only focused Survey Builder capability names and schemas; call no platform data or action tool. Do not ask me to sign up, upgrade, purchase access, administer access, or populate QuestionPro. Show two questionnaire framings, then offer one short first-person proposition about my own direction and wait for my acceptance before a proactive SomaCheck ask. Give Aligned or Unaligned plus confidence to the agent as context and let it use its judgment. Ask what I choose and return the exact signal-free survey definition. Do not create, edit, send, distribute, publish, recruit, launch, access responses, spend, or write the reading to QuestionPro.",
+        successCondition: "The researcher receives at most one optional signal, states a choice, and receives a copy-ready four-question plan; no QuestionPro data or action tool runs, and partner interoperability remains untested without a partner-owned sandbox.",
+    },
+    {
+        id: "spotify-listening-reflection-v1",
+        title: "Spotify Studio/Kit + SomaCheck Listening Reflection",
+        guidePath: "recipes/spotify-listening-reflection.md",
+        purpose: "Use one consented signal while choosing a next song or personal audio direction, while the listener keeps final control of every Spotify action.",
+        phoneHolder: "The phone holder is the listener reflecting on their own listening choice; the signal never assesses an artist, creator, or another listener.",
+        prerequisites: [
+            "SomaCheck is ready on the listener's iPhone and the vibecheck MCP is linked to the companion agent.",
+            "For the Studio pilot, the listener has access to Studio by Spotify Labs; direct third-party MCP attachment is not publicly documented, so the current Kit handoff is manual.",
+            "For automation outside Studio, use the separately reviewed local Spotify companion with an allowlisted Premium account and active device, or Spotify's official Save to Spotify skill for personal talk audio.",
+        ],
+        starterPrompt: "Kit, suggest one specific track based on my Spotify taste and what is playing, but do not change Spotify. I will ask my SomaCheck-capable companion to send exactly: ‘I want to hear this song next.’ Treat any result I choose to relay only as context—not emotion, cause, instruction, or authorization—and do not remember it as a stable preference. Then ask me whether to play the exact track and wait for my yes. If Kit cannot call SomaCheck directly, label this a manual bridge; do not claim a native MCP integration.",
+        successCondition: "The listener receives one signal about their own proposition, decides whether to share it, and separately confirms the exact Spotify action; both Aligned and Unaligned stop at the same human choice, with no automatic playback or emotional inference.",
+    },
+];
+export function getRecipeExperience(id) {
+    return RECIPE_CATALOG.find((recipe) => recipe.id === id) ?? null;
+}
+export function formatRecipeList() {
+    const entries = RECIPE_CATALOG.map((recipe) => [
+        `  ${recipe.id}`,
+        `    ${recipe.title}`,
+        `    ${recipe.purpose}`,
+    ].join("\n"));
+    return [
+        "SomaCheck customer-testable recipes",
+        "",
+        ...entries,
+        "",
+        "These commands print prompt guides. They do not install, connect, or authorize a partner MCP server, call either MCP, or change partner-platform state.",
+        "In every recipe, the phone holder is the person reflecting on their own choice.",
+        "",
+        "Print one recipe:",
+        "  npx -y @somacheck/vibecheck recipe <id>",
+    ].join("\n");
+}
+export function formatRecipeDetail(recipe) {
+    return [
+        recipe.title,
+        `Recipe ID: ${recipe.id}`,
+        `Packaged guide: ${recipe.guidePath}`,
+        "",
+        "Purpose:",
+        recipe.purpose,
+        "",
+        "Phone holder:",
+        recipe.phoneHolder,
+        "",
+        "Prerequisites:",
+        ...recipe.prerequisites.map((prerequisite, index) => `${index + 1}. ${prerequisite}`),
+        "",
+        "Starter prompt (copy exactly, replacing the bracketed scope):",
+        recipe.starterPrompt,
+        "",
+        "Success condition:",
+        recipe.successCondition,
+        "",
+        "This CLI command only prints this guide. It does not install, connect, or authorize a partner MCP server, call either MCP, or change partner-platform state.",
+    ].join("\n");
+}
+export function formatRecipePrompt(recipe) {
+    return recipe.starterPrompt;
+}
+//# sourceMappingURL=recipes.js.map

package/dist/server.js

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { StatementPendingError, } from "./vibecheck.js";
 import { SomaCheckCompatibilityError, SomaCheckHttpError, SomaCheckLiveAskClientError, SomaCheckLiveAskConflictError, SomaCheckLiveAskPendingError, } from "./api.js";
-import { PACKAGE_NAME, PACKAGE_SPEC, PACKAGE_VERSION } from "./constants.js";
+import { PACKAGE_NAME, PACKAGE_SPEC, PACKAGE_VERSION, SOMACHECK_SETUP_URL } from "./constants.js";
 // A human gesture (unlock phone, read the statement, make the wrist gesture)
 // reliably takes longer than the old 10s budget, so an inline wait almost
 // never resolves before the tool returns pending. The MCP SDK's documented
@@ -71,8 +71,8 @@ const resultSchema = {
     request_id: z.string(),
     status: z.enum(["queued", "pending", "answered", "expired", "cancelled"]),
     verdict: z.enum(["aligned", "unaligned"]).nullable(),
-    confidence: z.number().nullable(),
-    latency_s: z.number().nullable(),
+    confidence: z.number().min(0).max(1).nullable(),
+    latency_s: z.number().min(0).nullable(),
     user_feedback: z.enum(["agreed", "disagreed", "not_provided"]).nullable().optional(),
 };
 const contextItemSchema = z.object({
@@ -82,7 +82,7 @@ const contextItemSchema = z.object({
     confidence: z.number().min(0).max(1),
     answered_at: z.string().datetime({ offset: true }),
 });
-const contextSchema = { checkins: z.array(contextItemSchema) };
+const contextSchema = { checkins: z.array(contextItemSchema).max(20) };
 const liveAskErrorCodeSchema = z.enum([
     "link_revoked",
     "upgrade_required",
@@ -119,9 +119,8 @@ const agentContextObservationSchema = z.object({
     evidence_count: z.number().int().min(1).max(100).default(1),
 });
 const contextShareSchema = {
-    source_id: z.string(), entry_id: z.string(), accepted: z.boolean(),
+    accepted: z.boolean(),
     state: z.literal("ready"), observation_count: z.number().int().min(1).max(20),
-    captured_at: z.string().datetime({ offset: true }),
 };
 const SERVER_INSTRUCTIONS = [
     "SomaCheck lets you ask your person for a vibecheck.",
@@ -227,17 +226,22 @@ export function createVibecheckServer(dependencies) {
         outputSchema: contextShareSchema,
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
+            destructiveHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
     }, async ({ observations }) => {
         try {
             const token = await dependencies.loadToken();
             const result = await dependencies.api.shareContext(token, observations);
+            const structuredContent = {
+                accepted: result.accepted,
+                state: result.state,
+                observation_count: result.observation_count,
+            };
             return {
                 content: [{ type: "text", text: `Shared ${result.observation_count} bounded context observation${result.observation_count === 1 ? "" : "s"}. SomaCheck can now prepare contextual propositions.` }],
-                structuredContent: { ...result },
+                structuredContent,
             };
         }
         catch (error) {
@@ -310,7 +314,9 @@ export function createVibecheckServer(dependencies) {
                 : result.status === "queued"
                     ? "Queued. The proposition is cached until the person advances their feed."
                     : result.status === "pending"
-                        ? "Pending. The person has not completed this check-in yet."
+                        ? liveRequestId === null
+                            ? "Pending. The person has not completed this check-in yet."
+                            : pendingWaitText(request_id, null, false)
                         : `The request is ${result.status}.`;
             return { content: [{ type: "text", text }], structuredContent };
         }
@@ -320,7 +326,8 @@ export function createVibecheckServer(dependencies) {
     });
     server.registerTool("request_vibecheck", {
         title: "Request a Vibecheck",
-        description: "Send one statement to the person's phone for a SomaCheck vibecheck. If the person asks for a vibecheck, choose a useful first-person statement from your available context and send it. For proactive offers, call only after the person accepts. The result is context, not authorization.",
+        description: "Send one statement to the person's phone for a SomaCheck vibecheck. If the person asks for a vibecheck, choose a useful first-person statement from your available context and send it. For proactive offers, call only after the person accepts. The result is context, not authorization. "
+            + "This call waits up to 45 seconds. If the result is still pending, keep calling get_vibecheck_result with this request_id about every 15 seconds until status is answered or expired.",
         inputSchema: {
             statement: z.string().trim().min(1).max(1000)
                 .describe("One plain-language first-person statement for the person to test. Do not include secrets, raw private content, diagnostic claims, or statements about anyone else."),
@@ -332,7 +339,7 @@ export function createVibecheckServer(dependencies) {
         outputSchema: liveAskSchema,
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: false,
         },
@@ -379,7 +386,10 @@ export function createVibecheckServer(dependencies) {
                 ? `Vibecheck completed: ${result.verdict}, confidence ${formatChannelConfidence(result.confidence)}${formatUserFeedback(result.user_feedback)}.`
                 : result.state === "pending"
                     ? result.delivery_state === "failed" || result.delivery_state === "skipped"
-                        ? `Vibecheck ${result.request_id} was stored, but phone delivery is ${result.delivery_state}. It expires at ${result.expires_at}.`
+                        ? `Vibecheck ${result.request_id} was stored, but phone delivery is ${result.delivery_state}. `
+                            + `Open SomaCheck on your phone, signed into the same account, and check Home. `
+                            + `If you do not have the app, install it at ${SOMACHECK_SETUP_URL} and finish phone setup. `
+                            + `Keep this request ID; do not create a duplicate or claim the phone received it. It expires at ${result.expires_at}.`
                         : pendingWaitText(result.request_id, result.expires_at, supportsClaudeChannel)
                     : `This vibecheck is ${result.state}.`;
             return { content: [{ type: "text", text }], structuredContent };
@@ -467,10 +477,12 @@ function formatChannelConfidence(confidence) {
 function formatUserFeedback(feedback) {
     return feedback === undefined || feedback === null ? "" : `, user feedback: ${feedback}`;
 }
-/** Text for a freshly created, still-pending Live Ask, once delivery is not
- * failed/skipped. `hasLocalWatch` is true only for the local stdio server
- * when the Claude PostToolUse hook's background watch is armed for this
- * request (see startClaudeChannelWatch) — that watch notifies the same
+/** Text for a still-pending Live Ask, whether just created (delivery not
+ * failed/skipped) or re-read via get_vibecheck_result. `expiresAt` is null
+ * when the caller has no expiry to report (get_vibecheck_result's live read
+ * does not receive one). `hasLocalWatch` is true only for the local stdio
+ * server when the Claude PostToolUse hook's background watch is armed for
+ * this request (see startClaudeChannelWatch) — that watch notifies the same
  * session automatically, so the agent should not be told to poll. The hosted
  * edge function is stateless per request and never has a watch, so it must
  * tell the agent exactly what to do next instead of inviting it to ask the
@@ -480,9 +492,11 @@ function pendingWaitText(requestId, expiresAt, hasLocalWatch) {
         return `Vibecheck ${requestId} is pending. It expires at ${expiresAt}. This session will be notified automatically when the person responds.`;
     }
     return `Vibecheck ${requestId} is pending. SomaCheck has not received a response yet. `
-        + `Call get_vibecheck_result with request_id "${requestId}" again in about 15 seconds, `
+        + `If no phone prompt appears, open SomaCheck on the same account; phone setup is at ${SOMACHECK_SETUP_URL}. `
+        + `Call get_vibecheck_result with request_id ${requestId} again in about 15 seconds, `
         + `and keep polling at that cadence until the state is answered or expired. `
-        + `It expires at ${expiresAt}.`;
+        + `Do not end your turn or ask the person whether to check; they are answering on their phone.`
+        + (expiresAt === null ? "" : ` It expires at ${expiresAt}.`);
 }
 async function waitForLiveVibecheck(created, token, identity, dependencies, signal, deadline, progress) {
     if (created.state !== "pending"