@somacheck/vibecheck 0.6.9 → 0.6.11

package/dist/server.js

@@ -2,10 +2,22 @@ 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";
-const LIVE_ASK_WAIT_BUDGET_MS = 10_000;
+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
+// default tool-call timeout is 60s (see LIVE-ASK-CONTRACT.md); 45s leaves a
+// 15s margin for token loading, the create round trip, and result-read
+// overhead on top of the sleeps below, while covering most prompt gestures
+// inline. Overridable via `liveAskWait.budgetMs` so tests stay fast.
+const LIVE_ASK_WAIT_BUDGET_MS = 45_000;
+// Initial backoff, then steady 4s polling. The steady tail's length is sized
+// so the sum matches LIVE_ASK_WAIT_BUDGET_MS above — the wait loop below
+// stops as soon as either the array or the deadline is exhausted, so a
+// smaller injected budgetMs (tests) still ends early on the deadline check.
 const LIVE_ASK_POLL_DELAYS_MS = [
     1_000, 1_500, 2_500, 4_000,
+    4_000, 4_000, 4_000, 4_000, 4_000, 4_000, 4_000, 4_000, 4_000,
 ];
 const CLAUDE_CHANNEL_POLL_INTERVAL_MS = 2_000;
 const CLAUDE_CHANNEL_MAX_WATCH_MS = 15 * 60 * 1_000;
@@ -59,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({
@@ -70,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",
@@ -107,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.",
@@ -215,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) {
@@ -298,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 };
         }
@@ -308,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."),
@@ -320,7 +339,7 @@ export function createVibecheckServer(dependencies) {
         outputSchema: liveAskSchema,
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: false,
         },
@@ -367,8 +386,11 @@ 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} is pending. 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 };
         }
@@ -455,6 +477,27 @@ function formatChannelConfidence(confidence) {
 function formatUserFeedback(feedback) {
     return feedback === undefined || feedback === null ? "" : `, user feedback: ${feedback}`;
 }
+/** 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
+ * human. */
+function pendingWaitText(requestId, expiresAt, hasLocalWatch) {
+    if (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. `
+        + `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. `
+        + `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"
         || created.delivery_state === "failed"

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@somacheck/vibecheck",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "mcpName": "io.github.Sensie-agents/vibecheck",
   "description": "Send a consented vibecheck to SomaCheck and use the result as a signal.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sensie-app/Somacheck.git",
-    "directory": "packages/vibecheck"
+    "url": "git+https://github.com/Sensie-agents/vibecheck.git"
   },
   "type": "module",
   "bin": {
@@ -18,6 +17,7 @@
   "files": [
     "dist/*.js",
     "SKILL.md",
+    "recipes/**",
     "claude-marketplace/**"
   ],
   "scripts": {
@@ -40,7 +40,7 @@
     "tsx": "^4.23.1",
     "typescript": "^5.9.3"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   }

package/recipes/chattermill-research-reflection.md

@@ -0,0 +1,323 @@
+---
+title: Chattermill + SomaCheck Research Reflection
+recipe_id: chattermill-research-reflection-v1
+status: P1 researcher-side read-only reflection; aggregate metrics and generated highlights only
+audience: Researchers and CX analysts using Chattermill with an MCP-capable agent
+updated: 2026-09-05
+required_mcp_servers:
+  - chattermill
+  - vibecheck
+---
+
+# Chattermill + SomaCheck Research Reflection
+
+This recipe gives a Chattermill researcher one private SomaCheck check-in while
+shaping the researcher's own interpretation of customer-feedback insights. The
+researcher stays the only person who reads, decides, or acts. The recipe reads
+only aggregate metrics or generated highlights and performs no Chattermill
+write.
+
+Chattermill exposes a hosted read-only MCP surface
+(`https://app.chattermill.com/mcp`, Streamable HTTP). Its published OAuth
+protected-resource metadata advertises only the `mcp:read` scope alongside
+`openid profile email offline_access`; there is no write scope, and the server
+is documented as read-only. Existing Chattermill roles and permissions still
+apply, so an agent never sees data the researcher cannot already view.
+
+The SomaCheck reading is context for the researcher's own interpretation or
+next step. It is not truth, diagnosis, authorization, evidence about any
+individual customer, or a research decision. The researcher remains the
+authority.
+
+## Capability and access boundary
+
+Chattermill documents the hosted MCP as read-only and OAuth 2.1 authenticated
+at `https://app.chattermill.com/mcp`. A product or integration owner provides
+an organization-authorized connection or partner sandbox that can already
+view the named project's aggregate metrics and highlights. The provisioned MCP
+client completes Chattermill's OAuth flow at `auth.chattermill.com`. Running
+this recipe never asks the researcher to sign up, purchase access, administer
+access, or populate Chattermill data.
+
+The MCP server's protected-resource metadata advertises `mcp:read` as its only
+MCP scope. There is no write tool in the published contract. If a write
+surface appears at runtime anyway, this recipe still performs no write.
+
+This P1 recipe is researcher-side only. Do not use it to:
+
+- ask a customer, respondent, employee, candidate, patient, or student to
+  complete a SomaCheck;
+- retrieve individual feedback responses, verbatim comments, source quotes,
+  respondent identifiers, contact fields, or any free-text feedback;
+- retrieve observation clusters that surface representative verbatim snippets
+  or observation identifiers tied to individual feedback;
+- use a reading for customer targeting, eligibility, payment, ranking,
+  churn scoring, authenticity, quality, or performance evaluation;
+- write a SomaCheck reading, confidence, gesture, confirmation, or hidden
+  score into Chattermill, a dashboard, a tag, a theme, a highlight, an
+  insight, or any analytics record; or
+- create, edit, publish, delete, share, export, or otherwise mutate any
+  Chattermill project, theme, attribute, metric, dashboard, or insight.
+
+Participant- or customer-facing use stays blocked until a `respondent_private`
+architecture prevents researcher or platform access to individual readings,
+methodology and ethics review is complete, and Sensie gives explicit
+privacy/legal approval. Chattermill MCP access, read-only scope, or participant
+consent alone does not satisfy these gates.
+
+## Experience a researcher can run
+
+The researcher holds the phone and selects one existing Chattermill project
+supplied by the workspace owner, then provides one research question. The agent
+reads only that project's aggregate metrics (`get_metrics`) or generated
+highlights (`generate_highlights`), plus the discovery metadata needed to build
+the query (`list_themes`, `list_attributes`, `search_attributes`,
+`list_metric_options`). It never calls `get_feedback` (individual responses)
+or `search_observations` (observation identifiers and representative verbatim
+snippets), and never surfaces individual feedback, source quotes, respondent
+identifiers, or free text. The agent offers two defensible interpretations of
+what the aggregate signal suggests, then one short first-person proposition
+about the researcher's own interpretation or next step. After the researcher's
+typed choice, the agent stops. There is no Chattermill write.
+
+## Starter prompt
+
+```text
+Use Chattermill and SomaCheck to help me reflect on my own interpretation of
+customer-feedback insights for one named Chattermill project. 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 (get_metrics) or
+generated highlights (generate_highlights), plus discovery metadata
+(list_themes, list_attributes, search_attributes, list_metric_options) needed
+to build the query. Never call get_feedback or search_observations. Never
+surface individual feedback, source quotes, respondent identifiers, contact
+fields, or free text. Propose two defensible interpretations of what the
+aggregate signal suggests, with the tradeoff for each. Then 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 any individual customer. Ask what I choose in words. Keep the
+proposition, reading, confidence, and my confirmation out of Chattermill. Do
+not write to Chattermill; the hosted MCP is read-only. If the preconfigured
+connection, mcp:read, or a safe aggregate tool is absent, return the 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.
+```
+
+## Prerequisites and account access
+
+1. The researcher can complete a normal SomaCheck request through the connected
+   `vibecheck` MCP server (`request_vibecheck` and
+   `get_vibecheck_result`).
+2. A product or integration owner has provisioned an authorized organization
+   connection or partner sandbox that can already view the named project's
+   aggregate metrics and highlights. Existing Chattermill roles and permissions
+   apply; the MCP grants no access beyond the provisioned workspace.
+3. The provisioned MCP client is connected to exactly
+   `https://app.chattermill.com/mcp` and authenticated through the OAuth 2.1
+   flow Chattermill publishes at `auth.chattermill.com`. Do not substitute a
+   different host, path, or non-Chattermill endpoint.
+4. The workspace owner supplies one named existing Chattermill project (by name
+   or ID) whose aggregate metrics or generated highlights are enough for the
+   reflection task, with no need for individual responses or verbatim comments.
+   The researcher is not responsible for creating or populating it.
+5. No credential, OAuth token, API key, project ID containing PII, or
+   respondent identifier appears in chat, logs, prompts, or the SomaCheck
+   proposition.
+
+## Chattermill tool policy
+
+Chattermill publishes a hosted, read-only MCP (`mcp:read` scope). It documents
+eight tools in two groups: discovery tools and data tools. The agent must
+inspect the live tool list at runtime and use only the smallest tools that
+return aggregate or generated output. Treat the live schemas as
+runtime-discovered; do not assume undocumented tool names.
+
+| Purpose | Allowed surface | Rule |
+| --- | --- | --- |
+| Discover theme/category names | `list_themes` | Metadata only; names configured in the project, never feedback content |
+| Discover filterable attributes | `list_attributes` | Metadata only; attribute names, never feedback values |
+| Discover valid filter values | `search_attributes` | Metadata only for segment attributes (country, product, data source); never enumerate an identifier-bearing attribute such as email or customer ID |
+| Discover metric options | `list_metric_options` | Metadata only; chart types, metrics, frequencies, breakdown options |
+| Read aggregate quantitative data | `get_metrics` | Aggregate NPS, sentiment, volume, or trend metrics only |
+| Read generated highlights | `generate_highlights` | AI-generated summary of themes, issues, or trends only |
+| Read individual feedback responses | `get_feedback` | Prohibited in this recipe |
+| Search observation clusters with snippets | `search_observations` | Prohibited in this recipe; returns observation identifiers and representative verbatim snippets |
+| Any create, edit, publish, delete, share, export, or mutation | any write or mutation tool | Prohibited in this recipe |
+| Private reflection | `request_vibecheck`, optional `get_vibecheck_result` | One decision, one request, one stable pending handle |
+
+Do not broaden a connection to a root or all-tools endpoint to make this
+recipe work. If the runtime does not expose `get_metrics` or
+`generate_highlights`, label the Chattermill half untested and stop.
+
+## Exact cross-MCP workflow
+
+1. **Confirm the subject and scope.** State that the researcher is the phone
+   holder and the subject of the proposition. Name the one existing Chattermill
+   project supplied by the workspace owner (by name or ID) and the research
+   question.
+2. **Verify access honestly.** Confirm the client is connected to exactly
+   `https://app.chattermill.com/mcp` through Chattermill's OAuth flow and
+   that the `mcp:read` scope is present. Do not claim a live pass on
+   documentation, a fixture, or a connection that lacks the read scope.
+3. **Read only aggregate or generated output.** Call `get_metrics` or
+   `generate_highlights`, using discovery metadata (`list_themes`,
+   `list_attributes`, `search_attributes`, `list_metric_options`) only to
+   build the query. Do not call `get_feedback` or `search_observations`, and
+   do not surface individual feedback, source quotes, respondent identifiers,
+   contact fields, or free text.
+4. **Separate evidence from interpretation.** Label what the aggregate
+   metrics or highlights literally contain, what the agent infers, and what
+   the researcher's own judgment must still decide.
+5. **Propose two interpretations.** Offer two defensible interpretations of
+   what the aggregate signal suggests, with the tradeoff for each.
+6. **Choose one first-person proposition.** It must be short, first-person,
+   and about the researcher's own interpretation or next step. Do not include
+   project IDs containing PII, individual feedback, source quotes,
+   respondent identifiers, contact fields, or free text.
+7. **Establish one-ask consent.** If the researcher explicitly requested a
+   SomaCheck check-in in the current message, use
+   `consent_basis: "user_requested_vibecheck"`. Otherwise show the exact
+   proposition, wait for acceptance, and use
+   `consent_basis: "user_approved_statement"`.
+8. **Request once.** Call `request_vibecheck` with the approved statement and
+   a fresh UUID `idempotency_key`. Reuse it only to retry the identical
+   request after an ambiguous create failure.
+9. **Handle the real lifecycle.** A terminal response from
+   `request_vibecheck` uses `state: "completed"`; a later read uses
+   `status: "answered"`. If the initial response is `pending`, retain the
+   returned `live:<uuid>` handle and call `get_vibecheck_result` with it once
+   later. If it is still `pending`, `expired`, `cancelled`, or errors,
+   continue without a result. Never issue a replacement ask.
+10. **Return authority.** Separate observation (a valid gesture was
+    captured), interpretation (`aligned` or `unaligned` plus model
+    confidence), confirmation (what the researcher says), and choice (what the
+    researcher decides). `unaligned` may indicate possible inner conflict
+    relative to the proposition; it does not name a cause, choose an
+    interpretation, or justify a research claim.
+11. **Ask for words.** Ask the researcher which interpretation they choose,
+    whether they want a third option, or whether they want to stop. Follow
+    their typed choice.
+12. **Keep the signal out of Chattermill.** Do not call any write, mutation,
+    export, tag, theme, highlight, insight, or analytics tool. Do not store
+    the proposition, reading, confidence, confirmation, or gesture metadata
+    in Chattermill.
+13. **End the test.** Report the exact Chattermill tool names used and the
+    exact aggregate or generated fields returned, or report the copy-ready
+    interpretation when the Chattermill half is untested. Do not create,
+    edit, publish, delete, share, or export any Chattermill object.
+
+## Proposition examples
+
+Allowed:
+
+- "I can interpret this aggregate signal without reading individual
+  feedback."
+- "I have a clear reading of what these aggregate metrics suggest."
+- "I am ready to act on generated highlights without opening verbatim
+  comments."
+- "I want to keep individual responses out of my interpretation."
+- "I can state what this trend does and does not show."
+
+Not allowed:
+
+- "This customer is telling the truth."
+- "These respondents are engaged."
+- "This feedback proves the feature is broken."
+- "This customer should be flagged or deprioritized."
+- "This aggregate metric validates my hypothesis."
+
+## Visible success condition
+
+The test passes when:
+
+- the researcher selects one existing Chattermill project supplied by a
+  workspace owner whose provisioned connection can view its aggregate metrics
+  and highlights;
+- the agent reads only aggregate metrics (`get_metrics`) or generated
+  highlights (`generate_highlights`) through the hosted read-only
+  Chattermill MCP and reports the exact tool names used;
+- the agent never calls `get_feedback` or `search_observations`, and never
+  surfaces individual feedback, source quotes, respondent identifiers,
+  contact fields, or free text;
+- the researcher receives at most one optional SomaCheck check-in on their
+  phone on an exact first-person proposition about their own interpretation or
+  next step;
+- the agent presents the result as context, asks the researcher to state their
+  choice in words, and follows the typed choice;
+- the agent makes no Chattermill write, mutation, export, share, tag,
+  comment, or analytics call; and
+- no individual customer, respondent, or employee data enters the cross-MCP
+  flow.
+
+## Failure and degraded paths
+
+- **Read scope absent or OAuth failure:** Report the missing capability to the
+  product or integration owner; never request a token or API key in chat or ask
+  the researcher to sign up, purchase access, or administer access. Label the
+  Chattermill half untested, return the copy-ready interpretation, and stop.
+- **Runtime exposes only individual-response or observation tools:** Do not
+  call them. Label the Chattermill half untested and stop. Do not broaden
+  the connection to make this recipe work.
+- **MCP returns individual feedback, source quotes, respondent identifiers,
+  contact fields, or free text:** Stop immediately. Discard the individual
+  content from the agent context. Report the exact fields received and ask the
+  product or integration owner to revoke or limit the scope. Do not use the
+  individual content in any proposition, framing, or interpretation.
+- **SomaCheck unresolved:** Use the same `live:<uuid>` handle once later,
+  then proceed without a reading if still unresolved.
+- **Unreadable capture:** Offer a retry only if the researcher wants it;
+  unreadable is not a third interpretation.
+- **Researcher disagrees with the reading:** Follow the researcher's typed
+  choice without reconciliation or repetition.
+
+## Privacy boundary
+
+- Raw phone motion never reaches Chattermill or the agent.
+- Chattermill receives no proposition, reading, confidence, confirmation,
+  gesture metadata, or SomaCheck output through this recipe.
+- SomaCheck receives no Chattermill project ID containing PII, individual
+  feedback, source quote, respondent identifier, contact field, free-text
+  comment, or verbatim response.
+- No individual customer, respondent, or employee data is read into the agent
+  conversation, prompt, proposition, framing, or memory.
+- The Chattermill project remains unchanged. No write, mutation, export,
+  share, tag, comment, insight, or analytics call occurs.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and the subject of the proposition.
+- [ ] The client is connected to exactly `https://app.chattermill.com/mcp`
+      through Chattermill's OAuth 2.1 flow; no other host, path, or
+      non-Chattermill endpoint is used.
+- [ ] The `mcp:read` scope is present and no write scope is assumed.
+- [ ] No Chattermill credential, OAuth token, or API key appears in chat,
+      logs, or the SomaCheck proposition.
+- [ ] The agent reads only `get_metrics` or `generate_highlights`, using
+      discovery metadata only to build the query, and reports the exact
+      runtime tool names used.
+- [ ] The agent does not call `get_feedback` or `search_observations`.
+- [ ] No individual feedback, source quote, respondent identifier, contact
+      field, or free text appears in the conversation, proposition, or
+      interpretation.
+- [ ] The proposition is first-person and contains no Chattermill content.
+- [ ] At most one SomaCheck request is created for the choice.
+- [ ] Observation, interpretation, confirmation, and choice remain separate.
+- [ ] The researcher states a choice in words and the agent follows the typed choice.
+- [ ] The agent makes no Chattermill write, mutation, export, share, tag,
+      comment, or analytics call.
+- [ ] No individual customer, respondent, or employee data enters the
+      cross-MCP flow.
+
+## Sources
+
+- [Chattermill MCP server guide](https://docs.chattermill.com/en/articles/13943134-chattermill-mcp-server)
+- [Chattermill MCP endpoint](https://app.chattermill.com/mcp)
+- [Chattermill MCP protected-resource metadata](https://app.chattermill.com/.well-known/oauth-protected-resource/mcp)
+- [Chattermill MCP authorization-server metadata](https://app.chattermill.com/.well-known/oauth-authorization-server)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)
+- [MCP Customer-Testable Experience Catalog](../../../docs/agent-adoption/customer-experience-catalog.md)