# Skill: set a brand up in Shruwd

Shruwd (https://shruwd.io) measures how a brand appears in AI-generated answers, diagnoses
why it is or is not cited, and re-checks fixes to prove whether anything moved.

Everything below is doable over the REST API. There is no onboarding UI to drive
and nothing to scrape — one step needs a human, and it is called out in step 1.

## Interfaces, in order of preference

1. `shruwd-mcp` — a local stdio MCP server. Best if you are running in Claude
   Desktop, Claude Code or Cursor: the tools carry their own descriptions.
2. `@shruwd/sdk` — a typed TypeScript client. Best if you are writing code.
3. `https://shruwd.io/api/v1` — plain REST, described at `https://shruwd.io/openapi.json`.

## Inputs

- `name` and `domain` — the brand to track, e.g. `Waitlister` / `waitlister.me`
- `competitors` — the brands you expect to be compared against
- `prompts` — the questions buyers actually ask. Start with 10 to 25

No lists yet? After step 2, `POST https://shruwd.io/api/v1/brands/{brandId}/setup-suggestions`
drafts ten prompts and up to six competitors from the brand's homepage. Nothing is
added: review the draft with the human, then add what they keep in steps 3 and 4.
Three drafts per brand per day.

## Procedure

1. **Get a key — this step is the human's.** API keys are minted only with an
   interactive session, so an agent cannot create its own. Ask the account owner
   to sign in at https://shruwd.io, open **Account → API keys**, and create a key with
   read and write scope. Suggested message: *"Create a Shruwd API key under
   Account → API keys and paste it to me — I'll do the rest."*

   Keys look like `sh_live_...` and go in `Authorization: Bearer <key>`. Treat
   it as a secret: put it in an environment variable, never in a committed file.

   A key is bound to one workspace and never exceeds its holder's role there:
   reads need `viewer`, writes `editor`, creating or archiving a brand
   `owner`, and minting a log-ingest token `admin`. If you are expected to
   create the brand in step 2, ask an owner for the key. Refusals are
   `403 not_a_member` and `403 insufficient_role`.

2. **Create the brand.** `POST https://shruwd.io/api/v1/brands { name, domain }`. A caller who
   owns no workspace gets one automatically on this call — there is no workspace
   resource to create first. A short or common-word brand name ("Front") is
   refused with `context_terms_required` until you add `contextTerms`, words
   that mark a mention as being about this brand — otherwise every "front-end"
   counts as one.

3. **Add competitors, before any prompt.** `POST https://shruwd.io/api/v1/brands/{brandId}/entities`,
   one call each. Matching is exact on token boundaries, never fuzzy, because a
   false positive here silently corrupts every metric downstream. A short or
   common-word name is refused with `context_terms_required` until you supply
   `contextTerms` — the terms that make "Arc" mean the company rather than the
   word. If you need the human for those, ask now, before step 4.

4. **Add every prompt in one call.** `POST https://shruwd.io/api/v1/brands/{brandId}/prompts`.
   These are fixed for the brand and repeated every cycle, which is what makes
   week-over-week comparison meaningful — so write them as a buyer would ask, not
   as keywords, and change them rarely. The plan's prompt allowance is one pool
   across every brand in the workspace, not a per-brand limit; a batch that would
   exceed it is refused whole with `409 plan_limit`, carrying `limit`,
   `current` and `submitted`.

   The first measurement starts within minutes of the first prompts and measures
   only the prompts and competitors that exist at that moment. On the free plan it
   is the only measurement the domain ever gets, and there is none at all if step
   2 answered `snapshot: "already_taken"`. That is why competitors come first
   and the prompts go in together.

5. **Wait, then check.** Measurement is asynchronous: the first cycle starts
   within minutes of the prompts and completes within a day. Check after about
   fifteen minutes, then about once an hour, never in a tight loop:
   `GET https://shruwd.io/api/v1/brands/{brandId}/cycles`. It lists newest first, and on a weekly
   plan the first entry is next week's cycle, still `pending`. Skip pending
   cycles, which have not started, and read the newest one that has:

   - `running` — still measuring.
   - `complete` — the results are in.
   - `partial` — some runs failed. Report what exists and say so.
   - `failed` or `skipped_quota` — no new numbers. Say that rather than
     reporting older ones as new.

6. **Read the results, once per engine.**
   `GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=google_aio` and
   `GET https://shruwd.io/api/v1/brands/{brandId}/visibility?engine=chatgpt` — the brand's
   `engines` lists the ones its plan measures. Without `engine` the call
   returns Google AI Overviews only, so report each engine separately, never as
   one "AI visibility" number. `GET https://shruwd.io/api/v1/brands/{brandId}/findings` for the
   diagnosed causes and the fixes they recommend. Where the plan shows only its
   top findings, the list returns those and counts the rest in `locked` by
   severity: say how many are withheld rather than reporting the list as the
   whole set, and expect `403 not_entitled` on a locked one.

## Reading a metric correctly

This is the part agents most often get wrong, so check your output against it
before reporting anything.

Every metric comes back as a `DisplayableMetric`:

```json
{ "state": "ok", "point": 0.142, "lo": 0.081, "hi": 0.226, "n": 42 }
```

- `point`, `lo` and `hi` are proportions from 0 to 1: 0.142 is 14.2%.
- `state: "insufficient_data"` means fewer than ten responses exist. **It is not
  zero.** Say "not enough data yet", never "0%".
- Never quote `point` without `lo` and `hi`. The interval is usually wide, and a
  bare number reads as far more certain than the measurement is.
- Never say a metric "improved" or "dropped" from two point estimates. Movement
  requires non-overlapping intervals AND at least 5 percentage points of change.
  Shruwd applies both gates itself — report what it says, do not recompute it.

## Notes

- Engines tracked today: Google AI Overviews and ChatGPT. Google AI Mode is not tracked.
- On Starter and Pro, cycles run weekly. The free plan takes one snapshot at setup and
  no scheduled cycles. A manual run is `POST https://shruwd.io/api/v1/brands/{brandId}/cycles`.
- Plans, prices and limits, as markdown: https://shruwd.io/pricing.md
- Errors are `{ code, message, retryable, details? }`. Retry `429` and `5xx` with
  backoff and honour `Retry-After`; do not retry a `4xx` that is not `429`.
- Full documentation in one fetch: https://shruwd.io/llms-full.txt · index: https://shruwd.io/llms.txt
- Any docs page is raw markdown with `.md` appended, e.g.
  https://shruwd.io/docs/getting-started/overview.md