--- name: install-iterateto description: >- Install and configure the iterateTo feedback widget in a web app — add the embed, wire the project public key (pk_), optionally connect the MCP feedback queue, and record the setup in AGENTS.md. Use when the user wants to add iterateTo, add a feedback/bug-report widget, or collect in-context user feedback on their website or app. --- # Install iterateTo You are wiring the **iterateTo** feedback widget into the user's project. Work tool-first and verify each step. `{APP_URL}` below is the origin of the iterateTo instance (the dashboard host you fetched this skill from, e.g. `https://app.iterateto.com` or a self-hosted URL) — substitute it throughout. ## 1. Read the real project state Do not guess the framework. Run the CLI to read it: ```bash npx --yes iterateto@0.1.0 info --json ``` This prints the detected framework (Next.js / React / Vite / plain HTML / …), whether the widget is already installed, and where env lives. Trust this over your assumptions. If the CLI is unavailable, inspect the repo directly (`package.json`, `app/layout.tsx` or `index.html`). ## 2. Get the project public key The widget needs a **public key** that starts with `pk_`. It is safe to embed. - Ask the user for it, or point them to **{APP_URL}/dashboard/projects** to copy it (each project shows a ready-made snippet). - **Never invent, guess, or hard-code a key.** If you don't have one, stop and ask. ## 3. Install the embed Prefer the CLI — it writes the embed in the correct place for the detected framework and is idempotent: ```bash npx --yes iterateto@0.1.0 init --key pk_THE_ACTUAL_KEY --yes ``` `--yes` runs non-interactively (correct for you as an agent). If the user wants to review changes, drop `--yes`. If the CLI can't run, add the loader manually: ```html ``` Place it in the root layout's `` (Next.js: use `next/script` with `strategy="afterInteractive"`) or before `` in plain HTML. ## 4. Wire env (if the project keys off env) If the project prefers config in env rather than an inline attribute, put the public key in the project's env file (e.g. `NEXT_PUBLIC_ITERATETO_KEY=pk_...`) and reference it where the widget is mounted. The `pk_` is public, so a `NEXT_PUBLIC_`-style var is fine. Never place an `itr_` secret in client env. ## 5. Record the setup in AGENTS.md / CLAUDE.md So future agent sessions self-orient, append a short block to the user's `AGENTS.md` (or `CLAUDE.md`). Create the file if absent: ```md ## iterateTo The iterateTo feedback widget is installed. - Widget public key (`pk_`, safe to embed): - Dashboard / inbox: {APP_URL}/dashboard - Product Context + feedback over MCP: {APP_URL}/api/mcp (OAuth, or an environment-backed `itr_` personal token for local tools) - Docs: {APP_URL}/docs · Install skill: {APP_URL}/skill.md ``` Do not write any `itr_` secret into a committed file. ## 6. (Optional) Connect Product Context and feedback If the user wants the agent to use Product Context or triage feedback, connect the MCP server. For a local client, create a personal token (`itr_`, secret) under **{APP_URL}/dashboard/settings/api-keys**, set it as `ITERATETO_API_KEY` in the client process, and use the CLI to write only an environment-variable reference: ```bash export ITERATETO_API_KEY=itr_THE_ACTUAL_KEY npx --yes iterateto@0.1.0 mcp init --client codex --host {APP_URL} ``` Substitute `claude`, `cursor`, or `vscode` for another client. Hosted clients connect to `{APP_URL}/api/mcp` with OAuth. Never paste an `itr_` key into chat, a shared link, a one-click deeplink, or a committed file. For the complete connection workflow, install the skill at `{APP_URL}/mcp-skill.md`. ## 7. Verify - Confirm the config endpoint answers for the key: `curl {APP_URL}/api/widget-config/pk_THE_ACTUAL_KEY` → JSON with `"enabled": true`. - Start the app and confirm the launcher pill renders and opens the panel. - If you connected MCP, list the advertised tools, resolve a project, and run a read-only Product Context call before attempting a mutation. Report what you changed (files touched, where the key lives, whether MCP was connected) and link the user to {APP_URL}/docs for configuration and privacy.