---
name: terradium-setup
description: Set up a new Terradium project end to end over the hosted Terradium MCP server — brand profile, competitors, keyword research, tracked prompts and topics, and a first content plan drafted for the user to approve. Use when the user asks you to set up their Terradium project.
---

# Set up a Terradium project (hosted MCP)

You are setting up the user's Terradium project for them. Terradium tracks how
AI assistants (ChatGPT, Google AI Overviews, Perplexity, …) answer the questions
the user's customers ask, and writes articles to win those answers.

You talk to Terradium through the **`terradium` MCP server**. Its token is
scoped to exactly one project, so no tool takes a project id. If the
`terradium` tools are not available, tell the user to add the server (the
command or config is on the step they copied this prompt from) and restart
their agent, then stop.

> No MCP? The same flow over plain HTTP is at
> https://terradium.io/setup/rest.md.

The user is watching a checklist in the Terradium dashboard that ticks as each
step lands: brand profile → competitors → keyword research → prompts & topics →
first plan drafted.

## Rules

- **Ask, don't guess.** Each step below starts with a short question. Offer a
  suggestion when you can infer one from their website, but let the user
  confirm or correct it before you write it.
- **Confirm before spending.** `start_keyword_job` spends one keyword-research
  run and real provider cost. Show the seed keywords and get an explicit yes.
- **Stop at a drafted plan.** Never call `set_plan_status`, `generate_plan_item`,
  `generate_draft`, `generate_for_gap`, `publish_now`, `set_review_window` or
  `run_sample` during setup. The user approves the plan in the dashboard.
- **Keep the token secret.** Never write it into a file you commit or echo it
  back in full.
- Be brief. One question at a time, a short summary after each write.

## Steps

### 0. Look at the project

Call `get_project_details`. Note the project name and website. If you can read
the website (fetch it, or it is the repo you're in), skim it now so you can
suggest answers instead of asking cold.

### 1. Brand profile

Ask: *What do you sell, who do you sell it to, and which country and language
do your customers search in?*

Then call:

- `set_brand_profile` with `sells`, `audience`, `language` (ISO 639-1, e.g.
  `en`, `id`) and `country` (ISO 3166-1 alpha-2, e.g. `US`, `ID`). It replaces
  the whole profile, so always send all four.
- `set_brand_entity` with `orgName` (and `orgLogoUrl`, `sameAs` profile links,
  `author` if the user gives them). Skip fields you don't know rather than
  inventing them.

### 2. Competitors

Ask: *Which brands do you lose customers to?* Suggest 3–5 from what you know of
their market. Call `create_competitors` with their domains (e.g.
`["hubspot.com", "pipedrive.com"]`).

### 3. Seed keywords

Ask: *Which keywords do you want to rank for?*

If they have none, **suggest 10 to 20 seed keywords** from their website and
competitors — short, commercial phrases a customer would search. Show the list
and wait for the user to confirm or edit it. Do not continue without a
confirmed list.

### 4. Keyword research

Once the user confirms, call `start_keyword_job` with
`{"mode": "seed", "seeds": [...confirmed list]}`. Then poll `get_keyword_job`
with its `id` every 15–30 seconds until `status` is `completed` or `failed`. It
usually takes a few minutes; tell the user it's running.

If it fails:

- **"an active subscription is required"** — the user is on the free plan.
  Tell them: *"Keyword research needs the 7-day free trial. Start it from the
  Start trial button on the Terradium checklist (or
  https://app.terradium.io/settings/billing), then tell me to carry on."* Wait,
  then retry the same call.
- **"not available on this deployment"** — skip to step 5, then use the
  fallback in step 6.
- **a research limit** — tell the user, and use the fallback in step 6.
- `status: failed` — retry once; if it fails again, use the fallback in step 6.

### 5. Topics and prompts

Prompts are the questions customers ask an AI assistant. Topics group them.

From the keyword clusters (`pages` on the completed job) or, without them, the
confirmed seeds, propose **3–6 topics** and **10–20 questions**, worded the way
a person types into ChatGPT ("what's the best CRM for a small agency?"). Show
them, let the user edit, then:

1. `create_topics` with `{"names": [...]}`.
2. `create_prompts` with `{"texts": [...], "topics": ["<topic>"]}` — one call
   per topic, so each question is filed under its topic. Max 50 per call.

### 6. Draft the first content plan

- **With a completed keyword job:** call `plan_from_keyword_job` with
  `{"jobId": "<id>", "name": "<Project> — first plan"}`. Omit `planType` so the
  plan is sized to fit every cluster.
- **Fallback (no keyword job):** call `create_plan` with `{"name": ...}`, then
  `add_plan_items` with one item per confirmed seed: `title` (a working
  headline) and `primaryKeyword`.

The plan is created as a **draft**. Do not activate it.

### 7. Hand back

Tell the user, in a few lines: what you set, the plan's name and how many
articles it holds, and that it is waiting for their approval in **Plans** in
the Terradium dashboard. Nothing has been generated or published.