chore(cli): migrate from scripts/cookiy.sh to npm cookiy-cli

references/cookiy/cookiy-billing.md

@@ -23,29 +23,29 @@ Many operations cost money (recruit, synthetic interview, report generation, dis
 List wallet transaction history. Optionally filter by study or survey.
 
 ```
-scripts/cookiy.sh billing transactions [--limit <n>] [--cursor <iso8601>] [--study-id <uuid>] [--survey-id <sid>]
+cookiy billing transactions [--limit <n>] [--cursor <iso8601>] [--study-id <uuid>] [--survey-id <sid>]
 ```
 
 ### billing price-table
 
 Get current pricing for all operations.
 
 ```
-scripts/cookiy.sh billing price-table
+cookiy billing price-table
 ```
 
 ### billing balance
 
 Get current wallet balance.
 
 ```
-scripts/cookiy.sh billing balance
+cookiy billing balance
 ```
 
 ### billing checkout
 
 Get a Stripe checkout URL to top up the wallet. Amount must be a whole dollar (no cents), minimum $10.
 
 ```
-scripts/cookiy.sh billing checkout --amount-usd-cents <n>
+cookiy billing checkout --amount-usd-cents <n>
 ```

references/cookiy/cookiy-qual.md

@@ -31,15 +31,15 @@ Review Guide  ──→  (optional) show/edit the guide
 Fetch existing studies.
 
 ```
-scripts/cookiy.sh study list [--limit <n>] [--cursor <s>]
+cookiy study list [--limit <n>] [--cursor <s>]
 ```
 
 ### study create
 
 Create a new study. It automatically creates the discussion/interview guide (generated asynchronously).
 
 ```
-scripts/cookiy.sh study create --query <s> [--thinking <s>] [--attachments <s>]
+cookiy study create --query <s> [--thinking <s>] [--attachments <s>]
 ```
 
 | Flag | Required | Purpose |
@@ -54,7 +54,7 @@ Upload an image and get an s3 key back. The key can be used in `study create --a
 guide update payloads.
 
 ```
-scripts/cookiy.sh study upload --content-type <s> (--image-data <s> | --image-url <s>)
+cookiy study upload --content-type <s> (--image-data <s> | --image-url <s>)
 ```
 
 | Flag | Required | Purpose |
@@ -68,14 +68,16 @@ Check the current stage of a study (guide generation, recruitment, interviews, e
 whenever you need to know what's happening before taking the next step.
 
 ```
-scripts/cookiy.sh study status --study-id <uuid>
+cookiy study status --study-id <uuid>
 ```
 
 ---
 
 ## Waiting on Async Operations
 
-Guide and report generation expose a `wait` subcommand (see the relevant sub-reference) to block until complete. Use it to poll-wait until the operation completes. For all other progress checks, use `study status`.
+Guide and report generation expose a `wait` subcommand (see the relevant sub-reference) that
+polls `study status` every 15s and blocks until the operation completes. Use it when you need to
+wait-then-act. For all other progress checks, call `study status` yourself.
 
 ---
 

references/cookiy/cookiy-quant.md

@@ -15,55 +15,55 @@
 List surveys.
 
 ```
-scripts/cookiy.sh quant list
+cookiy quant list
 ```
 
 ### quant create
 
 Create a survey.
 
 ```
-scripts/cookiy.sh quant create --json '<obj>'
+cookiy quant create --json '<obj>'
 ```
 
 ### quant get
 
 Get survey detail.
 
 ```
-scripts/cookiy.sh quant get --survey-id <n>
+cookiy quant get --survey-id <n>
 ```
 
 ### quant update
 
 Update basic survey fields (e.g. title, format). Groups/questions cannot be modified after creation. The JSON is a subset of the create schema — provided keys overwrite, missing keys unchanged.
 
 ```
-scripts/cookiy.sh quant update --survey-id <n> --json '<obj>'
+cookiy quant update --survey-id <n> --json '<obj>'
 ```
 
 ### quant status
 
 Show overall survey status including recruitment progress.
 
 ```
-scripts/cookiy.sh quant status --survey-id <n>
+cookiy quant status --survey-id <n>
 ```
 
 ### quant report
 
 Fetch per-question response statistics. Returns JSON with a `question_summaries` field — present it visually or as text per the user's request.
 
 ```
-scripts/cookiy.sh quant report --survey-id <n>
+cookiy quant report --survey-id <n>
 ```
 
 ### quant raw-response
 
 Raw survey responses as CSV. Excludes incomplete by default. Output can be large — better redirect to a file.
 
 ```
-scripts/cookiy.sh quant raw-response --survey-id <n> [--include-incomplete]
+cookiy quant raw-response --survey-id <n> [--include-incomplete]
 ```
 
 ---

references/cookiy/cookiy-study-guide.md

@@ -12,24 +12,27 @@ Get the full discussion/interview guide. Returns JSON — convert it to a human-
 before showing to the user.
 
 ```
-scripts/cookiy.sh study guide get --study-id <uuid>
+cookiy study guide get --study-id <uuid>
 ```
 
 ### study guide wait
 
-Wait until the discussion/interview guide has been generated for the study.
+Block until the discussion/interview guide has finished generating (polls `study status` every 15s).
+Exits non-zero on timeout.
 
 ```
-scripts/cookiy.sh study guide wait --study-id <uuid>
+cookiy study guide wait --study-id <uuid> [--timeout-ms <n>]
 ```
 
+`--timeout-ms` defaults to `120000` (2 minutes).
+
 ### study guide update
 
 Partially update (patch) the discussion/interview guide. The patch is merged into the JSON returned
 by `study guide get`.
 
 ```
-scripts/cookiy.sh study guide update --study-id <uuid> --base-revision <s> --idempotency-key <s> [--change-message <s>] --json '<patch>'
+cookiy study guide update --study-id <uuid> --base-revision <s> --idempotency-key <s> [--change-message <s>] --json '<patch>'
 ```
 
 | Flag | Required | Purpose |

references/cookiy/cookiy-study-interview.md

@@ -11,7 +11,7 @@ Commands for fetching interview details for both real participant and synthetic
 List all interviews for a study.
 
 ```
-scripts/cookiy.sh study interview list --study-id <uuid> [--cursor <s>]
+cookiy study interview list --study-id <uuid> [--cursor <s>]
 ```
 
 ### study interview playback url
@@ -20,7 +20,7 @@ Get the playback URL of a specific interview. If `--interview-id` is not provide
 URLs for all interviews under the study.
 
 ```
-scripts/cookiy.sh study interview playback url --study-id <uuid> [--interview-id <uuid>]
+cookiy study interview playback url --study-id <uuid> [--interview-id <uuid>]
 ```
 
 ### study interview playback content
@@ -29,5 +29,5 @@ Get the content (transcript) of a specific interview. If `--interview-id` is not
 content for all interviews under the study.
 
 ```
-scripts/cookiy.sh study interview playback content --study-id <uuid> [--interview-id <uuid>]
+cookiy study interview playback content --study-id <uuid> [--interview-id <uuid>]
 ```

references/cookiy/cookiy-study-report.md

@@ -7,29 +7,32 @@
 Trigger report generation. Re-generates if a report already exists. Synthetic interviews are included by default; only pass `--skip-synthetic-interview` if the user explicitly asks to exclude them.
 
 ```
-scripts/cookiy.sh study report generate --study-id <uuid> [--skip-synthetic-interview]
+cookiy study report generate --study-id <uuid> [--skip-synthetic-interview]
 ```
 
 ### report wait
 
-Wait until the report has been generated.
+Block until report generation finishes (polls `study status` every 15s), then print the report
+share link. Exits non-zero on timeout.
 
 ```
-scripts/cookiy.sh study report wait --study-id <uuid>
+cookiy study report wait --study-id <uuid> [--timeout-ms <n>]
 ```
 
+`--timeout-ms` defaults to `300000` (5 minutes).
+
 ### report link
 
 Get the public URL for the report.
 
 ```
-scripts/cookiy.sh study report link --study-id <uuid>
+cookiy study report link --study-id <uuid>
 ```
 
 ### report content
 
 Get the report as markdown.
 
 ```
-scripts/cookiy.sh study report content --study-id <uuid>
+cookiy study report content --study-id <uuid>
 ```

references/cookiy/cookiy-study-synthetic-user.md

@@ -11,7 +11,7 @@ Commands for launching synthetic user (not real participant) interviews for a st
 Run synthetic user interviews with AI personas.
 
 ```
-scripts/cookiy.sh study run-synthetic-user start --study-id <uuid> [--persona-count <n>] [--plain-text <s>]
+cookiy study run-synthetic-user start --study-id <uuid> [--persona-count <n>] [--plain-text <s>]
 ```
 
 | Flag | Required | Purpose |

references/cookiy/cookiy.md

@@ -2,8 +2,30 @@
 
 Cookiy AI automates the full user research lifecycle — both qualitative (via AI-moderated
 interviews) and quantitative (via user surveys). All operations go through the
-[`scripts/cookiy.sh`](scripts/cookiy.sh) CLI (scripts folder is located under the same directory
-as this file). This is the only supported integration path — do not use alternative methods.
+[`cookiy-cli`](https://www.npmjs.com/package/cookiy-cli) npm package. This is the only
+supported integration path — do not use alternative methods.
+
+---
+
+## Install / Upgrade
+
+The CLI is distributed via npm. **Before the first command of any session**, ensure
+`cookiy` is installed and up to date on the user's machine:
+
+```bash
+# Check — if this prints a path, cookiy is installed
+command -v cookiy
+
+# First-time install (requires Node.js 18+)
+npm install -g cookiy-cli
+
+# Keep it current (run this at session start, or whenever a command errors oddly)
+npm update -g cookiy-cli
+```
+
+After install, every command is invoked as `cookiy <subcommand>` — **that is the only
+form used throughout this documentation**. If `command -v cookiy` comes back empty, run
+`npm install -g cookiy-cli` before proceeding.
 
 ---
 
@@ -37,5 +59,5 @@ or a response containing a login URL — handle it like this:
 **save-token** — Store an access token obtained from browser sign-in.
 
 ```
-scripts/cookiy.sh save-token <access_token>
+cookiy save-token <access_token>
 ```