# Quickstart: Cursor

> Set up Cursor with the Taggor rule file, sign in, and publish a first component from one prompt.

This page takes you from an empty folder to a component published to Staging, with
Cursor doing the writing. It assumes the [CLI quickstart](https://taggor.dev/docs/quickstart.md) step 1: you have
`taggor.mjs` in the project folder, with its hash checked. Creating the account and approving the sign-in
are yours; the agent never creates an account, accepts terms or types a secret.

## 1. Install the agent's instructions

```sh
node taggor.mjs init --agent cursor
node taggor.mjs agent install --agent cursor   # or: add it to a project that has taggor.json
```

This writes the rules to `.cursor/rules/taggor.mdc`, with `alwaysApply: true` so every chat in the project
gets them. The text is the same block the other agents get. Use Cursor's agent mode, which can run
terminal commands: the quickstart needs it to run `check` and `publish`.

## 2. Sign in

With a browser, you run it yourself, or the agent asks you to:

```sh
node taggor.mjs login
node taggor.mjs whoami
```

`login` prints a code and a URL; open the URL, check that the code matches, approve. Where there is no
browser (a remote machine, a container, a CI job), use an API key instead: in the portal, open Settings,
then API keys, create a key with the scopes the work needs, and set it as `TAGGOR_API_KEY` in the
environment that starts the agent. When the variable is set, it wins over any login and `whoami` shows
what the key can do. The key is shown once, to you: never paste it into the chat, into a file of the
project or into a prompt, and delete it when the work is done.

## 3. Ask for a component

Open the project folder in Cursor, start a chat in agent mode and paste the prompt below. Cursor asks
before it runs a command; read each one, and approve it only if it is one of the commands in the steps
below.

```text
Create a quote request form for my test site and publish it to staging.
Then give me the preview link and the script tag to paste on my site.
```

## 4. What you should see

Whatever the agent, the work goes in the same order. Each step says what you should see, so you can
tell when the agent is off the path.

1. **It checks who it is signed in as.** It runs `node taggor.mjs whoami --json`. If it gets exit code
   `3` (not signed in), it stops and asks you to run `node taggor.mjs login` and approve the sign-in in
   the browser. It never asks you for a password or a token.
2. **It learns your site before it writes.** It reads the colors, the font and the tone of your project
   or page, so the component looks like it belongs there.
3. **It writes one component** in `components/<tag>/src/index.tsx`: a single `defineTaggorComponent`
   call ([the contract](https://taggor.dev/docs/contract.md)). For a form that collects personal data it asks you for the
   privacy policy URL instead of inventing one.
4. **It checks, and repeats until the check passes.** It runs `node taggor.mjs check --json`. Exit code
   `0` means the gates passed. Exit code `6` means one failed: the JSON has `error.errors[]`, and each
   entry has a `code`, a `hint`, a `file` and a `line`. The agent fixes that file and runs `check`
   again. Every code has a page, [build diagnostics](https://taggor.dev/docs/diagnostics.md), with what it means and what
   to change. The agent never skips a check and never edits the check's rules.
5. **It publishes to Staging.** It runs `node taggor.mjs publish --json`, without `--channel`. The
   answer holds the build, the version, a `preview_url`, the sites the component is attached to
   (`sites`) and the ones it is not (`sites_not_attached`, each with the command that attaches it: a
   production site that only came from `taggor.json` is never attached by a publish). A build that fails comes back as exit code `6` with the same
   `error.errors[]`: back to step 4.
6. **It hands over to you.** It gives you the preview link, and `node taggor.mjs sites snippet` gives the
   script tag. Pasting the snippet on your site is yours: see [Install the snippet](https://taggor.dev/docs/snippet.md) and
   the [platform guides](https://taggor.dev/docs/platforms.md).

What the agent does not do unless you asked for exactly that in the conversation: move a component to
Production (`promote`), pass `--yes`, roll back, detach a component, delete anything, or choose a site or a channel
for you. If you see it reach for one of those, stop it.

## 5. When something goes wrong

- **Exit code 3:** not signed in. Run `login` (or set `TAGGOR_API_KEY`) and ask the agent to continue.
- **Exit code 6, build or gate:** the agent reads `error.errors[]` and fixes the file. If it fails the same
  code three times, open the code's page under [build diagnostics](https://taggor.dev/docs/diagnostics.md) and tell the agent
  what it says.
- **Any other failure:** the message ends with a code and a link to its page in
  [API and CLI errors](https://taggor.dev/docs/errors.md). Give the agent the `request_id` if the message has one.
- **The agent wants to skip a check, use `--yes` or paste a token into a file:** say no. Those are never
  the fix; the rules the installer wrote tell it so.

## Last real run of this prompt

Not run yet with Cursor. The date, the Cursor version and the result of the first real
run on staging go here when it is done. Until then, this page is written from the installed rules and the
CLI's behavior, not from a recorded session.