cookiy

# Cookiy

Cookiy gives your AI agent user-research capabilities. It designs
interview guides, conducts AI-moderated interviews with real or
simulated participants, and generates insight reports — all through
natural language.

---

## Part 1 — Setup

### Mandatory MCP preflight

Before doing anything else, ALWAYS verify that Cookiy MCP is available
for the current client.

Run this preflight on every Cookiy skill use:

1. Try calling `cookiy_introduce`.
2. If it succeeds, treat MCP as healthy and continue to Part 2.
3. If it fails because the tool is missing, the server is unreachable,
   authentication is broken, or the user asked for a different target
   environment, run the installer for the current client to repair or
   replace the MCP config.
4. After installation, call `cookiy_introduce` again. Only continue when
   it succeeds.

Do NOT ask the user whether to install MCP when the skill is being used.
The skill should self-heal by default.

### Setup-first conversation policy

- If the user is trying to install, connect, repair, or verify Cookiy,
  complete setup first. Do NOT ask research-goal, participant, or
  report-format questions before MCP is healthy.
- On `/cookiy` entry, if MCP health is unknown, run the preflight first.
  Only move into business discovery after setup succeeds or when the
  user explicitly asks what Cookiy can do.
- During setup, present only one next action at a time. For headless
  OAuth clients, surface the installer's single action block instead of
  inventing multiple options unless the installer actually fails.
- When `cookiy_introduce` is used only as a health check, NEVER dump the
  raw JSON payload to the user. Summarize the outcome in one sentence,
  such as: `Cookiy MCP is installed and verified successfully.`

Healthy MCP should be left alone. Reinstall only when one of these is
true:

- `cookiy_*` tools are unavailable
- MCP connection/authentication appears broken
- The MCP entry looks stale or was created under a legacy server name
- The user explicitly asks for a non-default environment such as
  `dev`, `dev2`, `preview`, `staging`, or `test`

### When repair/install is expected

- User mentions Cookiy, user research, voice interviews, or participant recruitment
- Any `cookiy_*` tool call fails with a connection or "tool not found" error
- User explicitly asks to set up or connect Cookiy
- User asks what Cookiy can do

### Install the MCP server

Identify which AI client you are running in (Codex, Claude Code, Cursor,
VS Code, Windsurf, Cline, OpenClaw, Manus, etc.) and install ONLY for
that client. Do not install for all clients at once.

Unless the user explicitly requests a different environment, install the
production MCP server. Production is the default and points to
`https://s-api.cookiy.ai`.

If the user explicitly asks for another environment, include that
environment alias in the installer command. Re-running the installer is
the approved repair/override path: it replaces the current Cookiy MCP
entry for that client with the requested target.

Pick the matching command:

| You are running in | Install command |
|---|---|
| Codex | `npx cookiy-mcp --client codex -y` |
| Claude Code | `npx cookiy-mcp --client claudeCode -y` |
| Cursor | `npx cookiy-mcp --client cursor -y` |
| Cline | `npx cookiy-mcp --client cline -y` |
| GitHub Copilot / VS Code | `npx cookiy-mcp --client vscode -y` |
| Windsurf | `npx cookiy-mcp --client windsurf -y` |
| OpenClaw | `npx cookiy-mcp --client openclaw -y` |
| Manus / headless sandbox | `npx cookiy-mcp --client manus -y` |
| Other / unknown | `npx cookiy-mcp -y` (auto-detects production) |

Examples for non-default environments:

- Codex dev2: `npx cookiy-mcp dev2 --client codex -y`
- Claude Code preview: `npx cookiy-mcp preview --client claudeCode -y`
- Cursor dev: `npx cookiy-mcp dev --client cursor -y`

If your agent is not in the table above but supports MCP over HTTP,
you can manually configure the MCP server URL: `https://s-api.cookiy.ai/mcp`
with OAuth authentication. See the MCP server's OAuth discovery at
`https://s-api.cookiy.ai/.well-known/oauth-authorization-server`.

For headless sandbox environments such as Manus, use
`npx cookiy-mcp --client manus -y`. The installer writes a resumable
OAuth helper bundle under `~/.mcp/<server>/`.

The installer will open the authorization page when possible and print
one explicit next step. If approval does not resume setup
automatically, paste the final callback URL or just the authorization
code back into the terminal.

### Verify the connection

After installation, call `cookiy_introduce` to confirm the MCP server
is connected and authenticated.

If the user's intent was only setup/connect/install/repair, stop after a
single success confirmation sentence. Do NOT automatically switch into a
research intake questionnaire after verification succeeds.

If authentication fails:
- Re-run the install command for the same target environment. This is
  the preferred repair path and may overwrite a stale or broken config.
- The OAuth token may have expired. The installer handles re-authentication.

### Orient the user only when asked

Present Cookiy's six capability modules (qualitative and quantitative are **parallel** — same agent, complementary methods; quantitative is not a prerequisite or downstream step for qualitative studies):

1. **Study Creation** — Describe a research goal and get an AI-generated discussion guide.
2. **AI Interview** — Simulate interviews with AI personas for quick insights.
3. **Discussion Guide** — Review and edit the interview script before going live.
4. **Recruitment** — Recruit real participants for AI-moderated interviews.
5. **Report & Insights** — Generate analysis reports and shareable links.
6. **Quantitative survey** — When Cookiy has this capability enabled for your workspace, create structured questionnaires, list them, share respondent links and question layout (via Cookiy tools), and pull response data for analysis. Parallel to qualitative studies; Cookiy does not expose third-party admin consoles or non-Cookiy product names.

Present these in plain language. Do not expose raw tool names to the user.

---

## Part 2 — Workflow Orchestration

Cookiy is a workflow-aware MCP server, not a raw REST passthrough.
Every operation must go through the official `cookiy_*` MCP tools.
Follow the tool contract and workflow state machines in the reference files.

### Intent Router

| User wants to... | Workflow | Reference file |
|---|---|---|
| Create a new study or research project | Study Creation | study-creation.md |
| Run simulated or AI-to-AI interviews | AI Interview | ai-interview.md |
| View or edit the discussion guide | Guide Editing | guide-editing.md |
| Recruit real participants | Recruitment | recruitment.md |
| Generate, check, or share a report | Report & Insights | report-insights.md |
| Author or analyze quantitative questionnaires (when server integration is configured) | Quantitative survey | — (see `cookiy_help` topic `quantitative`) |
| Natural-language study progress (“how is recruitment?”, “is the report ready?”) | Prefer: `cookiy_activity_get` | tool-contract.md |
| Add cash credit (USD cents) before paid actions | Direct: `cookiy_billing_cash_checkout` | tool-contract.md |
| Check account balance | Direct: `cookiy_balance_get` | — |
| List existing studies | Direct: `cookiy_study_list` | — |
| Learn what Cookiy can do | Direct: `cookiy_introduce` | — |
| Get workflow help on a topic | Direct: `cookiy_help` (`overview`, `study`, `ai_interview`, `guide`, `recruitment`, `report`, `billing`, `quantitative`; common aliases accepted) | — |

When the user's intent spans multiple workflows (e.g., "create a study
and run interviews"), execute them sequentially in the order listed above.

### Universal Rules

See tool-contract.md for the complete specification.

**Response handling:**
- ALWAYS read `structuredContent` first. Fall back to `content[0].text` only when `structuredContent` is absent.
- ALWAYS check `next_recommended_tools` in each response. Prefer the server's recommendation over your own judgment.
- ALWAYS obey `status_message` — it contains server-side behavioral directives, not just informational text.
- When `presentation_hint` is present, format output accordingly.
- For user-facing progress questions, prefer **`cookiy_activity_get`** first; use atomic tools only for drill-down.
- For recruitment truth, prefer evidence in this order: `cookiy_interview_list` > `cookiy_recruit_status` > the latest `cookiy_recruit_create` response > `cookiy_study_get.state`. The current public contract does not expose a separate `sync` flag on `cookiy_recruit_status`; the server already performs the billing-aware reconciliation it needs before returning status.
- NEVER describe recruitment as started/stopped from preview-only output.

**Identifiers:**
- NEVER truncate, reformat, or summarize `study_id`, `job_id`, `interview_id`, `base_revision`, or `confirmation_token`.

**Payment:**
- On HTTP 402: prefer `structuredContent.data.payment_summary` and `checkout_url`; if those fields are absent, fall back to `error.details`.
- To add cash credit outside a specific 402 flow, use `cookiy_billing_cash_checkout`, then confirm with `cookiy_balance_get`.
- `cookiy_balance_get` returns cash credit and per-product paid counters; OAuth signup bonus is folded into cash credit, not exposed as a separate `experience_bonus` field.
- Cash credit may apply to study creation, simulated interviews, report access, and recruitment when balance remains.
- When both exist, product-specific paid credits are consumed before cash credit.

**URLs:**
- NEVER construct URLs manually. ONLY use URLs from tool responses.
- NEVER guess undocumented REST paths.

**Agent boundary:**
- After recruitment payment, check `cookiy_recruit_status` first and `cookiy_interview_list` second before deciding whether to retry `cookiy_recruit_create`.
- Do not promise background monitoring unless a real automation layer exists outside the current MCP call.

**Constraints:**
- `interview_duration` max 15 minutes. `persona.text` max 4000 chars. `interviewee_personas` max 20. `attachments` max 10.

### Canonical reference

The server's developer portal spec endpoint provides the authoritative
tool reference. If a tool behaves differently from this skill's
description, the server's runtime behavior takes precedence.