@somacheck/vibecheck 0.6.10 → 0.6.11

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@somacheck/vibecheck",
-  "version": "0.6.10",
+  "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)

package/recipes/dovetail-research-reflection.md

@@ -0,0 +1,204 @@
+---
+title: Dovetail + SomaCheck Research Reflection
+recipe_id: dovetail-research-reflection-v1
+status: P1 researcher-side only
+audience: Researchers using Dovetail with an MCP-capable agent
+updated: 2026-09-03
+required_mcp_servers:
+  - dovetail
+  - vibecheck
+---
+
+# Dovetail + SomaCheck Research Reflection
+
+Use this recipe when a researcher wants a private, consented signal about their
+own response to research work held in Dovetail. It supports reflection on
+question wording, study design, and evidence interpretation. It does not assess
+participants and does not add SomaCheck readings to the research record.
+
+The reading is context for the researcher. It is not truth, a diagnosis,
+authorization, evidence about a participant, or a research decision. The
+researcher remains the authority.
+
+## Launch boundary
+
+This P1 recipe is **researcher-side only**. The person holding the phone and
+receiving the SomaCheck result must be the researcher interacting with the
+agent.
+
+Do not use this recipe to:
+
+- ask a participant or employee to complete a SomaCheck;
+- read, infer, compare, rank, monitor, or gate a participant;
+- export a participant reading, confidence, or confirmation into Dovetail;
+- tag, score, or characterize a transcript, highlight, contact, response, or
+  participant using a SomaCheck result;
+- decide eligibility, compensation, research quality, truthfulness, or whether
+  evidence should be included; or
+- run a live respondent workflow.
+
+Participant-facing use stays blocked until a `respondent_private` architecture
+technically prevents researcher or platform access to individual readings, a
+methodology and ethics review is complete, and Mike gives explicit approval.
+Documentation or workspace access is not approval to cross this boundary.
+
+## Prerequisites
+
+1. The researcher has linked the `vibecheck` MCP server to their own SomaCheck
+   account and can see `request_vibecheck` and `get_vibecheck_result`.
+2. The agent has the Dovetail MCP connection authorized by the researcher. Use
+   Dovetail's hosted endpoint, `https://dovetail.com/api/mcp`, or its documented
+   self-hosted server. Keep API tokens in the MCP client's secret configuration,
+   never in prompts, propositions, comments, or logs.
+3. The researcher names the exact Dovetail doc in scope. Access to a workspace
+   is not consent to search the whole workspace.
+4. The source is allowlisted: a researcher-authored research brief, discussion
+   guide, study plan, or de-identified researcher-authored synthesis.
+
+Never open raw interviews, transcripts, recordings, highlights, channel data,
+contacts, participant identifiers, or participant-authored responses for this
+recipe. If the selected Dovetail artifact mixes allowed planning material with
+participant content, stop and ask for a researcher-authored, de-identified
+summary.
+
+## Dovetail tool policy
+
+Use the smallest read scope that answers the researcher's request.
+
+| Purpose | Dovetail MCP tools | Rule |
+| --- | --- | --- |
+| Locate the named planning artifact | `get_doc`, or `list_docs` only when the researcher supplied a title rather than an ID | Use `get_doc` directly for a researcher-supplied ID. Do not list the workspace or search content when the ID is already known. |
+| Read the planning artifact | `get_doc_content` | Read only an allowlisted researcher-authored doc. |
+| Record a chosen next step | `create_comment` | Optional; call only after the researcher explicitly approves the exact comment. Never include the reading or confidence. |
+| Broad or participant-bearing content | `search_workspace`, project-data, highlight, channel, contact, and file-download tools | Do not call in this recipe. |
+| Other writes | project, folder, doc, data, tag, upload, and import creation tools | Not part of this recipe. Require a separate, explicit user request. |
+
+## Exact cross-MCP workflow
+
+Follow these steps in order. Never call Dovetail and SomaCheck in a way that
+makes the reading an automatic write condition.
+
+1. **Confirm the subject and scope.** State that the researcher is reflecting
+   on their own response. Name the one Dovetail doc to read.
+2. **Retrieve only the approved artifact.** If the researcher supplied a doc ID,
+   resolve it directly with `get_doc`. If they supplied only a title, use
+   `list_docs` to match that exact title, then resolve it with `get_doc`. Read the
+   approved doc with `get_doc_content`. Do not call `search_workspace`. Stop if
+   the doc contains participant-authored or identifying material.
+3. **Separate evidence from interpretation.** Summarize:
+   - what the planning artifact literally says;
+   - what the agent infers may need attention; and
+   - two or more reasonable options the researcher could choose.
+4. **Choose one first-person proposition.** It must express the researcher's
+   present experience or choice, not a claim about participants. Do not place
+   Dovetail content, participant text, names, project identifiers, or secrets in
+   the proposition.
+5. **Establish one-ask consent.** If the researcher explicitly asked for a
+   SomaCheck vibecheck in the current message, call `request_vibecheck` with
+   `consent_basis: "user_requested_vibecheck"`. Otherwise show the exact
+   proposition, wait for acceptance, and use
+   `consent_basis: "user_approved_statement"`.
+6. **Request once.** Call `request_vibecheck` with the approved statement and a
+   fresh UUID as `idempotency_key`. Reuse that UUID only to retry the same
+   statement after an ambiguous create failure. Never repeat an ask to seek a
+   preferred result.
+7. **Handle the exact result.** `request_vibecheck` reports a terminal answer as
+   `state: "completed"`; a later `get_vibecheck_result` read reports the same
+   lifecycle point as `status: "answered"`. Treat either as the terminal result
+   and keep four layers distinct: 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` means possible inner conflict relative to the proposition; it
+   does not identify a cause. If the initial response is `pending`, retain its
+   `live:<uuid>` handle and call `get_vibecheck_result` with that exact handle
+   once later. Do not create a replacement request. If that read is still
+   `pending`, is `expired` or `cancelled`, or errors, continue without a result;
+   do not infer one or start another request.
+8. **Return authority.** Offer the options to revise, investigate, proceed,
+   pause, or leave the artifact unchanged. A typed researcher choice overrides
+   the signal.
+9. **Keep the signal private.** Do not write the verdict, confidence, gesture,
+   or confirmation to Dovetail. If the researcher asks to record a next step,
+   show a signal-free comment first and call `create_comment` only after exact
+   approval.
+
+## Proposition examples
+
+Good propositions are short, first-person, and about the researcher:
+
+- “I can explain why this question asks one thing at a time.”
+- “I want to use this discussion guide in its current form.”
+- “My interpretation separates what participants said from what I inferred.”
+- “I am ready to treat this synthesis as one input to the next design choice.”
+- “I want to investigate a competing explanation before I proceed.”
+
+Never send propositions such as:
+
+- “This participant is telling the truth.”
+- “This transcript is high quality.”
+- “These users support the conclusion.”
+- “This employee is aligned with the company.”
+
+## Trigger and anti-trigger rules
+
+Trigger this recipe when the researcher explicitly asks to reflect with
+SomaCheck. The agent may also **offer** one check when the researcher is choosing
+between defensible question phrasings, sees tension between evidence and an
+interpretation, or says that something in the design feels off but is hard to
+name. An offer must include the exact proposition and must not call the tool
+until accepted.
+
+Do not trigger when:
+
+- the task is ordinary Dovetail retrieval, summarization, tagging, or export;
+- the proposed subject is anyone other than the researcher;
+- the source contains raw or identifiable participant material;
+- the researcher has already made a clear typed choice;
+- the result would determine inclusion, quality, compensation, performance, or
+  another consequential outcome; or
+- a vibecheck was already used for the same decision.
+
+## Consent, privacy, and failure behavior
+
+Linking the MCP servers is setup, not blanket consent. A proactive check always
+requires acceptance of its exact wording. Never send raw conversations,
+Dovetail text, participant data, identifiers, secrets, or diagnostic claims to
+SomaCheck. Raw phone motion never goes to the agent or Dovetail.
+
+If Dovetail authorization fails, ask the researcher to repair the connection;
+never request that they paste a token. If the document's provenance or
+de-identification is unclear, stop before reading it. If SomaCheck reports an
+unreadable capture, request a retry only if the researcher wants one; unreadable
+is not a third interpretation. If the request expires, is cancelled, or errors,
+continue without a reading. Never infer a result. If the result and the
+researcher's words differ, follow the researcher's words and preserve the
+difference rather than reconciling it into a score.
+
+## Verification checklist
+
+- [ ] Both MCP servers expose their expected tools; no credential appears in
+      chat or logs.
+- [ ] The agent names one researcher-authored, participant-free Dovetail doc.
+- [ ] Broad search and disallowed Dovetail data, highlight, channel, contact,
+      and download tools are not called.
+- [ ] The proposition is first-person and contains no Dovetail or participant
+      content.
+- [ ] A proactive ask waits for acceptance; an explicit user request does not
+      add a redundant consent prompt.
+- [ ] One decision creates at most one `request_vibecheck` request and preserves
+      its stable pending handle.
+- [ ] The response distinguishes observation, interpretation, confirmation, and
+      choice.
+- [ ] No reading, confidence, confirmation, or participant inference is written
+      to Dovetail.
+- [ ] Any Dovetail comment contains only the researcher's explicitly approved,
+      signal-free next step.
+- [ ] Participant-facing behavior remains blocked by the `respondent_private`,
+      methodology/ethics, and Mike-approval gates.
+
+## Sources
+
+- [Dovetail MCP server documentation](https://developers.dovetail.com/docs/mcp)
+- [Dovetail API overview](https://docs.dovetail.com/integrations/dovetail-api)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)