optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/naver-searchadvisor/scripts/robots.mjs

@@ -0,0 +1,77 @@
+/** Parse a robots.txt file without fetching it. */
+export function parseRobots(text) {
+  const groups = [];
+  const sitemaps = [];
+  let current = null;
+  let hasRule = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const field = line.slice(0, colon).trim().toLowerCase();
+    const value = line.slice(colon + 1).trim();
+    if (field === 'sitemap') {
+      if (value) sitemaps.push(value);
+    } else if (field === 'user-agent') {
+      if (!value) continue;
+      if (!current || hasRule) {
+        current = { agents: [], rules: [] };
+        groups.push(current);
+        hasRule = false;
+      }
+      current.agents.push(value.toLowerCase());
+    } else if ((field === 'allow' || field === 'disallow') && current) {
+      hasRule = true;
+      // RFC 9309: an empty rule does not restrict access.
+      if (value) current.rules.push({ type: field, path: value });
+    }
+  }
+  return { groups, sitemaps };
+}
+
+const unreserved = /^[A-Za-z0-9._~-]$/;
+const hex = n => `%${n.toString(16).padStart(2, '0').toUpperCase()}`;
+
+// Compare normalized octets. Keep encoded reserved octets distinct from raw delimiters.
+function normalize(value) {
+  let result = '';
+  for (let i = 0; i < value.length;) {
+    if (value[i] === '%' && /^[0-9a-f]{2}$/i.test(value.slice(i + 1, i + 3))) {
+      const byte = parseInt(value.slice(i + 1, i + 3), 16);
+      const character = String.fromCharCode(byte);
+      result += unreserved.test(character) ? character : hex(byte);
+      i += 3;
+    } else {
+      const point = value.codePointAt(i);
+      const character = String.fromCodePoint(point);
+      result += point > 127 ? [...Buffer.from(character)].map(hex).join('') : character;
+      i += character.length;
+    }
+  }
+  return result;
+}
+
+function matchRule(rule, path) {
+  const anchored = rule.endsWith('$');
+  const body = anchored ? rule.slice(0, -1) : rule;
+  const pattern = '^' + body.split('*').map(part => normalize(part).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + (anchored ? '$' : '');
+  return new RegExp(pattern).test(path);
+}
+
+/** RFC 9309: merge all groups matching the crawler product token. */
+export function robotsVerdict(parsed, agent, path) {
+  if (normalize(path).split('?', 1)[0] === '/robots.txt') return { allowed: true, reason: 'robots.txt는 암묵적으로 허용', matched_rules: [] };
+  const userAgent = agent.toLowerCase();
+  let groups = parsed.groups.filter(group => group.agents.some(name => name !== '*' && userAgent.includes(name)));
+  if (!groups.length) groups = parsed.groups.filter(group => group.agents.includes('*'));
+  if (!groups.length) return { allowed: true, reason: '해당 로봇에 적용되는 그룹 없음', matched_rules: [] };
+
+  const normalizedPath = normalize(path);
+  const matches = groups.flatMap(group => group.rules).filter(rule => matchRule(rule.path, normalizedPath));
+  if (!matches.length) return { allowed: true, reason: '일치하는 규칙 없음', matched_rules: [] };
+  const octets = rule => normalize(rule.path.replace(/\$$/, '').replaceAll('*', '')).replace(/%[0-9A-F]{2}/g, '_').length;
+  const max = Math.max(...matches.map(octets));
+  const matched_rules = matches.filter(rule => octets(rule) === max);
+  const winner = matched_rules.find(rule => rule.type === 'allow') ?? matched_rules[0];
+  return { allowed: winner.type === 'allow', reason: `${winner.type === 'allow' ? 'Allow' : 'Disallow'}: ${winner.path}`, matched_rules };
+}

package/skills/optbrew/modules/seranking-seo/skills/seo-ai-search-share-of-voice/GUIDE.md

@@ -0,0 +1,94 @@
+> Example output: examples/seo-ai-search-share-of-voice-wix-com-20260427/REPORT.md (upstream-only reference; route through optbrew)
+
+# AI Search Share of Voice
+
+Compare AI-search visibility for a target brand against competitors across every major LLM engine, then analyse the topic clusters each brand owns and where gaps exist.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- User provides: (a) target domain and its brand name, (b) list of competitor domains and brand names, (c) country (default: `us`), and (d) optionally, which engines to analyse (default: all supported: `ai-overview`, `chatgpt`, `perplexity`, `gemini`, `ai-mode`).
+
+## Process
+
+1. **Leaderboard snapshot** `DATA_getAiOverviewLeaderboard`
+   - Pull the AIO leaderboard for the target domain's category in the target country.
+   - Capture mention counts and share percentages per engine, per domain.
+
+2. **Heatmap table**
+   - Build a table: rows = domains (target + competitors), columns = engines, cells = % share of voice.
+   - Highlight the leader per engine and the worst performer.
+
+3. **Prompt sampling per domain** `DATA_getAiPromptsByBrand`, `DATA_getAiPromptsByTarget`
+   - For each domain (target and each competitor):
+     - Pull 10 ChatGPT prompts where the domain appears as a source (link mention).
+     - Pull 10 ChatGPT prompts where the brand is mentioned by name.
+   - Save query text and the exact sources cited so the user can validate.
+
+4. **Topic clustering**
+   - Group prompts by theme (e.g., pricing, feature comparison, tutorials, alternatives, reviews).
+   - For each brand, note which clusters it dominates and which it is absent from.
+
+5. **Gap and recommendation synthesis**
+   - Identify 3 to 5 topic clusters where the target underperforms competitors despite having relevant content.
+   - Recommend specific actions: new content angles, structured data additions, partnerships with frequently-cited sources, comparison pages, FAQ/How-To schema.
+
+## Output format
+
+Create a folder `seo-ai-search-share-of-voice-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-ai-search-share-of-voice-{target-slug}-{YYYYMMDD}/
+├── 01-leaderboard.md         # raw leaderboard per engine
+├── 02-heatmap.md             # visual heatmap table
+├── 03-prompts-{domain}.md    # one file per domain with 20 sampled prompts
+├── 04-topic-clusters.md      # cluster membership per brand
+└── REPORT.md                 # executive summary
+```
+
+`REPORT.md` follows this shape:
+
+```markdown
+# AI Search Share of Voice: {target brand} vs competitors
+
+## Summary
+- Target: {target} ({share}% across all engines)
+- Leader: {leader brand} ({share}%)
+- Target rank: {n} of {total}
+
+## Heatmap
+
+| Domain | AI Overview | ChatGPT | Perplexity | Gemini | AI Mode |
+|---|---|---|---|---|---|
+| {target} | {%} | {%} | {%} | {%} | {%} |
+| {comp1} | ... | ... | ... | ... | ... |
+
+## Who owns what
+
+### {target brand}
+Strong in: {cluster 1}, {cluster 2}
+Absent from: {cluster 3}, {cluster 4}
+
+### {competitor 1 brand}
+...
+
+## Topic cluster ownership
+
+| Cluster | Leader | Share | Target position | Gap |
+|---|---|---|---|---|
+| Pricing | {brand} | {%} | {n} | {% behind} |
+| Alternatives | {brand} | {%} | {n} | {% behind} |
+| Tutorials | {brand} | {%} | {n} | {% behind} |
+
+## Top 5 actions to close gaps
+1. {action with target cluster}
+2. ...
+```
+
+## Tips
+
+- Do not hallucinate citation counts. If the API returns zero prompts for a given domain/engine, report zero, do not estimate.
+- For each competitor, validate the brand-name match in the prompt text. Sometimes "Wix" appears in a sentence about "wiktionary" or a person's name. Flag ambiguous matches in the raw-prompt file.
+- `base_domain` scope is the default; do not narrow to `subdomain` unless the user asks.
+- Respect Data API rate limit: 10 requests per second. With 5 domains and 2 prompt queries per engine per domain, pace the loop.
+- The report is not a one-time artefact. Recommend the user re-run monthly and diff results to see ranking momentum.

package/skills/optbrew/modules/seranking-seo/skills/seo-api/GUIDE.md

@@ -0,0 +1,186 @@
+> Live with the SE Ranking MCP at `https://api.seranking.com/mcp`. Tool schemas are introspected live; this skill never relies on a frozen snapshot of the API surface.
+
+# SE Ranking API Integration Architect
+
+Help developers ship real integrations against the SE Ranking SEO Data API and Project API. The deliverable is either a **code recipe** (ready-to-paste cURL / Python / TypeScript / MCP-tool-call sequence) or **live wiring** of Project API state (create projects, add keywords, configure audits, set up AIRT prompts), or both. The skill knows the entire 195-tool surface, the credit and rate-limit cost of every call, and the canonical setup story for every major MCP client.
+
+## Prerequisites
+
+- **SE Ranking MCP connected** at `https://api.seranking.com/mcp`. Single API key authenticates both `DATA_*` and `PROJECT_*` tools through the unified gateway. If `/mcp` doesn't show `se-ranking`, the skill emits the install command and stops — see `references/auth-and-keys.md`.
+- **(Optional) `WebFetch`** for fetching deep guides at `seranking.com/api/data/*` and `seranking.com/api/project/*` when the request needs prose beyond JSON Schema.
+- User provides: an integration goal in plain language (e.g., "build a rank tracker for client X", "pull all backlinks for these 50 domains into BigQuery weekly", "configure an audit + AIRT prompts for a new project"). The skill interviews only when the goal is ambiguous.
+
+## Process
+
+1. **Preflight.**
+   - Confirm the SE Ranking MCP is reachable. If not, emit:
+     ```bash
+     claude mcp add --transport http se-ranking https://api.seranking.com/mcp
+     ```
+     and stop. See `references/auth-and-keys.md` for OAuth vs. `X-Api-Key` header tradeoffs and headless / CI patterns.
+   - Call `DATA_getSubscription` (0 credits). Record `units_left`, plan status, expiration — `units_left` is the figure to forecast against, and it gets printed in the cost forecast in step 5. Optionally also call `DATA_getCreditBalance` for its `{ limit, used }` view — but the two are **not** aliases: they report different remaining-credit numbers that do not reconcile (an ~8.6M gap is normal), so treat `getSubscription.units_left` as the source of truth.
+
+2. **Clarify the goal.** Ask 1–3 questions only if the goal is ambiguous. Skip when the user already spelled it out. Useful follow-ups:
+   - "Is this a one-off run, a recurring job (daily/weekly), or a long-lived integration in your product?"
+   - "Target country / language / device — or worldwide?"
+   - "Are we operating on a project you already own in SE Ranking, or just researching domains?"
+
+3. **Identify the API surface(s).** Map the goal to one or both of:
+   - **Data API** — research-shaped data on any domain, no prior account setup. Credit-billed. See `references/api-surface-map.md` § "Data API surfaces".
+   - **Project API** — operations on the user's own SE Ranking projects (rank tracking, audits, AIRT, backlink groups, marketing plan, sub-accounts). Subscription-limit-billed, not credit-billed. Requires Business or Enterprise plan. See `references/api-surface-map.md` § "Project API surfaces".
+   - Many real integrations span both — e.g., a rank-tracker setup uses `PROJECT_createProject` + `PROJECT_addKeywords` + `PROJECT_runPositionCheck`, then reports use `DATA_getDomainKeywords` for the same domain.
+
+4. **Map to tools / endpoints.** For every step in the integration, name:
+   - The MCP tool: `` `DATA_getDomainKeywords` `` or `` `PROJECT_addKeywords` ``.
+   - The underlying REST endpoint + HTTP verb (e.g., `GET /v1/domain/keywords`).
+   - The credit cost (Data API) or limit consumed (Project API). Source costs from `references/rate-limits-and-credits.md` and the per-endpoint pages at `seranking.com/api/data/*` — MCP tool `description` fields carry input schemas and usage notes but **not** credit costs.
+   - If a tool needs an ID the user didn't supply (project ID, search engine ID, geo region name, language code), insert the prerequisite `*list*` or `*available*` call before it. See `references/api-surface-map.md` § "ID resolution".
+
+5. **Forecast cost.** Sum credit cost across all Data API calls. For Project API calls, surface plan-limit impact (e.g., "this consumes 1 Site + 50 Keywords + ~500 Audit Pages from your plan"). Compare against:
+   - `units_left` from step 1 — if insufficient, surface and stop with the upgrade link.
+   - Plan limits if Project API tools are involved — `PROJECT_getUserProfile` returns current usage; flag if the integration would push a limit over.
+
+6. **Pick execution mode.** Confirm with the user explicitly:
+   - **Code mode** — emit ready-to-paste cURL, Python (`requests`), TypeScript (`fetch`), and MCP-tool-call variants. The developer runs them. Default for read-only research, recurring jobs the user wants to own, and anything they want to deploy outside their Claude session.
+   - **Live mode** — execute the integration step by step via MCP. Confirm every mutating call. Default for one-off Project API setup (new project, add keywords, configure audit, set up AIRT prompt group, etc.) where the user wants the state to exist by the end of this conversation.
+   - **Hybrid** — wire up the one-time setup live, emit code for the recurring workload (e.g., "I created the project and added the 50 keywords for you; here's the daily-run Python script to pull positions and write them to BigQuery").
+
+7. **Execute or emit.**
+   - **Code mode** — write `code/curl.sh`, `code/python.py`, `code/typescript.ts`, `code/mcp-calls.md`. Each file is a complete runnable example, not a fragment. Include error handling for `429` (rate limit) and `403` (insufficient credits). See `references/integration-patterns.md` for canonical pattern snippets.
+   - **Live mode** — for each *mutating* call (`PROJECT_create*`, `PROJECT_add*`, `PROJECT_delete*`, `PROJECT_update*`, `DATA_createStandardAudit`, `DATA_createAdvancedAudit`, etc.), print a single-line confirmation:
+     ```
+     About to call PROJECT_createProject(domain="acme.com", name="ACME Inc — Rank Tracker", country="us").
+     Consumes: 1 "Site" from your subscription. Proceed? [y/N]
+     ```
+     Wait for explicit `y` / `yes`. On anything else, fall back to code mode and emit the equivalent code instead of executing. Read-only calls (`DATA_get*`, `DATA_list*`, `PROJECT_get*`, `PROJECT_list*`) run without confirmation. Log every call to `evidence/03-execution-log.md` with timestamp, args, response status.
+
+8. **Synthesise `RECIPE.md`.** Always written, regardless of mode. The deliverable a developer reads to understand what was built or how to build it. See output format below.
+
+## Output format
+
+Folder `seo-api-{slug}-{YYYYMMDD}/` where `{slug}` is a kebab-case summary of the goal (e.g., `acme-rank-tracker`, `bulk-backlinks-bigquery`).
+
+```
+seo-api-{slug}-{YYYYMMDD}/
+├── RECIPE.md                       (primary deliverable — what was built or how to build it)
+├── code/
+│   ├── curl.sh                     (cURL one-liners + multi-step bash)
+│   ├── python.py                   (idiomatic requests-based script)
+│   ├── typescript.ts               (fetch + zod-validated responses)
+│   └── mcp-calls.md                (MCP-tool-call sequence — same workflow, agent-native)
+└── evidence/
+    ├── 01-preflight.md             (credit balance, subscription status, MCP connectivity check)
+    ├── 02-cost-forecast.md         (per-call cost breakdown, plan-limit deltas, total)
+    ├── 03-ids-resolved.md          (Project API / search-engine IDs, geo codes resolved upfront — omit if none needed)
+    └── 04-execution-log.md         (every MCP call executed, with args + status — omit in pure code mode where nothing ran)
+```
+
+Top-level: `RECIPE.md` + `code/`. The `evidence/` folder preserves the reasoning trail; auditors lean on `02-cost-forecast.md` and the execution log. `03` and `04` are conditional — a run with no ID lookups and no executed calls (pure code-mode advice) ships just `01` + `02`.
+
+`RECIPE.md` follows this shape:
+
+```markdown
+# {Integration Title}: {target}
+
+> Run dated {YYYY-MM-DD} · Mode: {code | live | hybrid} · Total cost: {n} credits + {plan-limits consumed}
+
+## Goal
+
+{1–2 sentences. What was asked, what's being shipped.}
+
+## API surface map
+
+| Step | MCP tool | REST endpoint | Verb | Cost |
+|------|----------|---------------|------|------|
+| 1    | `DATA_getCreditBalance` | `/v1/account/subscription` | GET | 0 credits |
+| 2    | `PROJECT_listProjects` | `/v1/account/projects` | GET | 0 (plan limit: read) |
+| 3    | `PROJECT_createProject` | `/v1/projects` | POST | 1 Site from plan |
+| ...  | ... | ... | ... | ... |
+
+## Auth & setup
+
+{cURL header / Python session / TypeScript fetch wrapper showing exactly how to authenticate. Reference `references/auth-and-keys.md` for OAuth vs. header tradeoffs.}
+
+## Cost forecast
+
+- Credit cost (Data API): {n} credits ({explanation per call})
+- Plan-limit consumption (Project API): {Sites: n, Keywords: n, Audit Pages: n, AIRT Prompts: n}
+- Your balance at run time: {units_left} credits, {plan limits available}
+- {OK / WARNING: this integration would push X over plan limit}
+
+## Recipe
+
+### Option A — cURL
+
+(complete bash script in `code/curl.sh`)
+
+### Option B — Python
+
+(complete script in `code/python.py`)
+
+### Option C — TypeScript
+
+(complete script in `code/typescript.ts`)
+
+### Option D — MCP tool calls
+
+(agent-native sequence in `code/mcp-calls.md` — for when this integration lives inside another Claude/Cursor/Codex workflow)
+
+## Rate limit & retry strategy
+
+- Data API: 10 RPS, Project API: 5 RPS. Pace sequentially for batched workflows; small-batch parallelism (≤3 concurrent) is safe.
+- 429 handling: exponential backoff with jitter (1s → 2s → 4s → 8s, ±20% jitter). 5xx: same. Treat 403 "Insufficient funds" as terminal — no retry.
+
+## What's running now (live mode only)
+
+{Bullet list of MCP calls that were executed, with their outcomes. Pulled from `evidence/04-execution-log.md`.}
+
+## What you still need to do
+
+{Concrete next steps for the developer. E.g., "Run `python.py` daily via cron at 06:00 UTC", "Open the project at https://online.seranking.com/...", "Add a webhook for rank changes via Settings → Notifications".}
+
+## Linked docs
+
+- {Direct links to the relevant pages on `seranking.com/api/data/*` and `seranking.com/api/project/*`.}
+
+## When to escalate to another skill
+
+- `seo-content-brief` — once your integration is pulling keyword data, this skill turns it into editor briefs.
+- `seo-technical-audit` — if the integration involves website audits, this skill interprets the audit output.
+- `seo-drift baseline` — if the integration's job is to track a domain over time, snapshot it first.
+```
+
+## Tips
+
+- **Single API key authenticates everything.** `API_TOKEN` (or `X-Api-Key` header for headless) covers both `DATA_*` and `PROJECT_*`. The legacy split into separate Data and Project keys is gone — passing both still works as headers for backwards compatibility, but you can use just `X-Api-Key` now. See `references/auth-and-keys.md`.
+- **Rate limits are per-API-key, not per-IP.** All threads / workers / servers sharing one key contribute to the same 10-RPS (Data) or 5-RPS (Project) budget. For production fan-outs, mint multiple keys via the API Dashboard.
+- **Failed requests are free.** 4xx and 5xx never consume credits. Don't over-engineer cost protection for normal error retries.
+- **Project API limits are not credits.** They consume your subscription's "Sites", "Keywords", "Audit Pages", "AIRT Prompts" quotas. Surface plan-limit impact upfront for any mutating call — these limits are stickier than credits because the user has to upgrade their plan to lift them, not just buy a credit pack.
+- **Confirm before mutating.** `PROJECT_create*`, `PROJECT_add*`, `PROJECT_delete*`, `PROJECT_update*`, `DATA_create*Audit`, `DATA_deleteAudit` all permanently modify account state. Always print a one-line summary (tool, args, what gets consumed) and wait for `y`/`yes` before calling.
+- **Use the right ID resolution tool.** Most "I want to operate on project X / keyword Y" requests need an ID lookup first. See `references/api-surface-map.md` § "ID resolution" for the full table. Common cases:
+  - Project IDs → `PROJECT_listProjects` (or `PROJECT_listOwnedProjects` / `PROJECT_listSharedProjects` for sub-account setups).
+  - Search engine for rank tracking → pass `country_code` directly to `PROJECT_addSearchEngine` (ISO 3166-1 alpha-2). Only fall back to `PROJECT_getAvailableSearchEngines` for regional engines (Catalonia, Turkish-Cypriot Cyprus).
+  - SERP locations → `DATA_getSerpLocations`.
+  - Languages → `PROJECT_getGoogleLanguages`.
+  - Regions for local rank tracking → `PROJECT_getAvailableRegions` (use the verbatim `name` field; abbreviations are rejected).
+- **For exports, poll the status endpoint.** Async endpoints (`/backlinks/export`, `/keywords/export`) return a task ID; subsequent polls of `*ExportStatus` count against the rate limit but cost 0 credits. Start with a 5s poll interval; exponential backoff if the task is large.
+- **Check the MCP tool description before WebFetching docs.** Every MCP tool exposes its full input schema, defaults, and usage notes via the protocol — e.g. `DATA_getDomainCompetitors` documents its own ~60KB response cap. One thing the descriptions do *not* carry: credit costs — for those, use `references/rate-limits-and-credits.md` and the public per-endpoint pages.
+- **Large list endpoints can overflow the MCP transport.** `DATA_getDomainCompetitors` on a popular domain — and `DATA_getDomainKeywords` / `DATA_getAllBacklinks` on big domains — return responses past the MCP client's inline token limit; the result is auto-saved to a file instead. Recover it with a `jq` slice on the saved file, or call the REST endpoint directly (raw REST has no size cap). See `references/api-surface-map.md`.
+- **For "show me Swagger / OpenAPI for the MCP"** — point the developer at MCP Inspector (`npx @modelcontextprotocol/inspector https://api.seranking.com/mcp`) or `mcp-scan`. Both walk the live tool/prompt/resource catalogue. A canonical MCP→OpenAPI converter is on the roadmap; for now the inspector output is the source of truth.
+
+## Works well with
+
+- **Predecessors:** none — entry point for any API integration question.
+- **Successors (when the integration starts producing data):**
+  - `seo-content-brief` — when the integration pulls keyword research that should become editor briefs.
+  - `seo-page` — when one URL from the integration needs a keep/refresh/consolidate/kill verdict.
+  - `seo-drift baseline` — to snapshot a domain or URL before the integration starts running, so regressions are detectable.
+  - `seo-technical-audit` — when the integration involves audit runs and the output needs prioritisation.
+  - `seo-ai-search-share-of-voice` — when the integration tracks AIRT visibility and needs a competitive read.
+
+## References
+
+- `references/auth-and-keys.md` — API key formats, OAuth vs. header, headless / CI patterns, key rotation.
+- `references/rate-limits-and-credits.md` — 10 RPS / 5 RPS, credit billing models, plan-limit consumption, error codes (429, 403), exponential-backoff template.
+- `references/api-surface-map.md` — full routing table (which API owns what) + ID resolution table + decision tree for "which tool do I need".
+- `references/integration-patterns.md` — five canonical recipes copy-paste-ready: rank tracker setup, bulk backlink export, audit pipeline, AIRT visibility tracker, keyword research bulk job.

package/skills/optbrew/modules/seranking-seo/skills/seo-api/references/api-surface-map.md

@@ -0,0 +1,207 @@
+# API Surface Map
+
+The decision tree for "which API and which tool do I need". Pulled from the live MCP server's tool catalogue plus the canonical docs at `seranking.com/api/*`.
+
+## Top-level split
+
+| API | Owns | Billed against | Required plan |
+|---|---|---|---|
+| **Data API** | Research-shaped data on any domain. No prior account setup. | Credits. | Any with API credits. |
+| **Project API** | Operations on the user's own SE Ranking projects. | Plan limits (Sites / Keywords / Audit Pages / AIRT Prompts). | Business or Enterprise. |
+
+**Both APIs share a single API key.** A request lands on Data API or Project API based on its endpoint path (`/v1/backlinks/*` vs `/v1/projects/*`), not based on which key you sent.
+
+## Data API surfaces
+
+### Backlinks (~30 tools, prefix `DATA_*Backlinks*` / `DATA_*RefDomains*` / `DATA_*Ips*`)
+
+Read backlink profile of any domain.
+
+- **Summary & metrics:** `DATA_getBacklinksSummary`, `DATA_getBacklinksMetrics`, `DATA_getBacklinksCount`.
+- **Lists:** `DATA_getAllBacklinks`, `DATA_getBacklinksRaw`, `DATA_listNewLostBacklinks`.
+- **Anchors:** `DATA_getBacklinksAnchors`.
+- **Referring domains:** `DATA_getBacklinksRefDomains`, `DATA_getTotalRefDomainsCount`, `DATA_getNewLostRefDomainsCount`, `DATA_listNewLostReferringDomains`.
+- **Referring IPs / subnets:** `DATA_getReferringIps`, `DATA_getReferringIpsCount`, `DATA_getReferringSubnetsCount`.
+- **Authority:** `DATA_getDomainAuthority`, `DATA_getDomainAuthorityHistory`, `DATA_getDistributionOfDomainAuthority`, `DATA_getPageAuthority`, `DATA_getPageAuthorityHistory`, `DATA_getBacklinksAuthority`.
+- **History:** `DATA_getCumulativeBacklinksHistory`, `DATA_getNewLostBacklinksCount`.
+- **Indexed pages:** `DATA_getBacklinksIndexedPages`.
+- **Export (async):** `DATA_exportBacklinksData` → `DATA_getBacklinksExportStatus`.
+
+### Domain analysis (~12 tools)
+
+Read keyword / traffic / competitor / ad profile of any domain.
+
+- **Overview:** `DATA_getDomainOverviewWorldwide` (global), `DATA_getDomainOverviewDatabases` (per-region), `DATA_getDomainOverviewHistory` (12-month).
+- **Keywords:** `DATA_getDomainKeywords` (full list; supports `url` param for per-URL).
+- **Pages:** `DATA_getDomainPages` (top pages by traffic).
+- **Subdomains:** `DATA_getDomainSubdomains`.
+- **Competitors:** `DATA_getDomainCompetitors`, `DATA_getDomainKeywordsComparison`.
+- **Ads:** `DATA_getDomainAdsByDomain`, `DATA_getDomainAdsByKeyword`.
+- **URL-level overview:** `DATA_getUrlOverviewWorldwide`.
+
+> **`DATA_getDomainCompetitors` 60KB overflow.** For popular domains the response (up to 500 rows) exceeds the MCP client's inline token limit and is auto-saved to a file rather than returned inline. Recover it with a `jq` slice on the saved file — e.g. `jq -r '.data[:15][] | [.domain, .common_keywords] | @tsv' <saved-file>`. This is an MCP-transport limit only; the raw REST endpoint `GET /v1/domain/competitors` returns the full JSON uncapped. The same overflow can hit other large list endpoints — `DATA_getDomainKeywords`, `DATA_getAllBacklinks` — on big domains.
+
+### Keyword research (~7 tools)
+
+- `DATA_getRelatedKeywords`, `DATA_getSimilarKeywords`, `DATA_getLongTailKeywords`, `DATA_getKeywordQuestions`.
+- `DATA_exportKeywords` (bulk export).
+
+### SERP (~6 tools)
+
+Real-time top-100 SERP results.
+
+- **Task-based (recommended for batches):** `DATA_getSerpTasks` (list), `DATA_getSerpTaskResults`, `DATA_getSerpTaskAdvancedResults`.
+- **Synchronous:** `DATA_getSerpResults`.
+- **Locations:** `DATA_getSerpLocations`.
+- **HTML dump:** `DATA_getSerpHtmlDump` (raw SERP HTML for diagnostic).
+
+### Website audit — on-demand (~6 tools, lives under DATA)
+
+For one-off audits of any site (vs. Project-attached audits below).
+
+- **Create:** `DATA_createStandardAudit`, `DATA_createAdvancedAudit`.
+- **Status:** `DATA_getAuditStatus`, `DATA_listAudits`.
+- **Report:** `DATA_getAuditReport`, `DATA_getCrawledPages`, `DATA_getIssuesByUrl`, `DATA_getAuditPagesByIssue`.
+- **Manage:** `DATA_updateAuditTitle`, `DATA_recheckAudit`, `DATA_deleteAudit`, `DATA_getAuditHistory`.
+
+### AI Search (~10 tools, prefix `DATA_getAiSearch*`)
+
+LLM-engine visibility data.
+
+- **Overview:** `DATA_getAiSearchOverview`, `DATA_getAiSearchLeaderboard`.
+- **Per-brand / per-target:** `DATA_getAiSearchBrand`, `DATA_getAiSearchPromptsByBrand`, `DATA_getAiSearchPromptsByTarget`.
+- **Page-level:** `DATA_getAiVisibilityPages`, `DATA_getAiVisibilityPrompts`, `DATA_getAiVisibilityResponses`.
+- **Sources / topics / sentiment / models / aliases / scores:** the `DATA_getAiVisibility*` family.
+- **Reports:** `DATA_getAiVisibilityReports`.
+
+### Account & system (~4 tools)
+
+- `DATA_getSubscription` — plan info. Returns `{ subscription_info: { status, units_limit, units_left, start_date, expiraton_date } }`. **`units_left` is the figure to forecast against** — it matches the official credit-system docs.
+- `DATA_getCreditBalance` — returns `{ limit, used }`. **Not an alias of `getSubscription`:** the two report different remaining-credit figures that do not reconcile against `limit` (an ~8.6M gap observed in testing). Use it as a secondary view only; forecast from `getSubscription.units_left`.
+- `DATA_getUserProfile` — user identity + workspace.
+
+## Project API surfaces
+
+Project API mutates the user's account. Confirm all `create / add / delete / update` calls before invoking.
+
+### Project management (~15 tools)
+
+- **List:** `PROJECT_listProjects`, `PROJECT_listOwnedProjects`, `PROJECT_listSharedProjects`.
+- **CRUD:** `PROJECT_createProject`, `PROJECT_updateProject`, `PROJECT_deleteProject`.
+- **Groups:** `PROJECT_listProjectGroups`, `PROJECT_createProjectGroup`, `PROJECT_updateProjectGroup`, `PROJECT_deleteProjectGroup`, `PROJECT_moveProjectsToGroup`.
+- **Sharing:** `PROJECT_shareProject`.
+- **Summary:** `PROJECT_getSummary`, `PROJECT_getSeoPotential`.
+- **Brand:** `PROJECT_getSiteBrand`, `PROJECT_saveSiteBrand`.
+
+### Rank tracking — keywords & search engines (~25 tools)
+
+- **Keywords CRUD:** `PROJECT_listKeywords`, `PROJECT_addKeywords`, `PROJECT_updateKeyword`, `PROJECT_deleteKeywords`.
+- **Keyword groups:** `PROJECT_listKeywordGroups`, `PROJECT_createKeywordGroup`, `PROJECT_updateKeywordGroup`, `PROJECT_deleteKeywordGroup`, `PROJECT_moveKeywordsToGroup`.
+- **Tags:** `PROJECT_listTags`, `PROJECT_addTag`, `PROJECT_updateTag`, `PROJECT_deleteTag`.
+- **Search engines:** `PROJECT_getSearchEngines`, `PROJECT_addSearchEngine`, `PROJECT_updateSearchEngine`, `PROJECT_deleteSearchEngine`, `PROJECT_getAvailableSearchEngines`, `PROJECT_getAvailableRegions`, `PROJECT_getGoogleLanguages`.
+- **Positions:** `PROJECT_getPositionHistory`, `PROJECT_runPositionCheck`, `PROJECT_setKeywordPosition`, `PROJECT_getKeywordStats`, `PROJECT_getCheckDates`, `PROJECT_getHistoricalDates`.
+- **GSC integration:** `PROJECT_getGoogleSearchConsole`.
+- **Stats:** `PROJECT_getAdsStats`.
+
+### Competitors (~7 tools)
+
+- `PROJECT_listCompetitors`, `PROJECT_addCompetitor`, `PROJECT_deleteCompetitor`.
+- `PROJECT_getCompetitorPositions`, `PROJECT_getCompetitorSerp10`, `PROJECT_getCompetitorSerp100`, `PROJECT_getAllCompetitorsMetrics`.
+
+### Website audit (Project-attached, ~15 tools)
+
+For ongoing audits tied to a project. Distinct from on-demand audits via `DATA_*` above.
+
+- **Create & manage:** `PROJECT_createAudit`, `PROJECT_recheckAudit`, `PROJECT_deleteAudit`, `PROJECT_updateAuditTitle`, `PROJECT_listAudits`.
+- **Settings:** `PROJECT_getAuditSettings`, `PROJECT_updateAuditSettings`, `PROJECT_resetAuditSettings`.
+- **Sitemaps & source pages:** `PROJECT_listAuditSitemaps`, `PROJECT_addAuditSitemap`, `PROJECT_deleteAuditSitemap`, `PROJECT_listAuditSourcePages`, `PROJECT_addAuditSourcePages`, `PROJECT_deleteAuditSourcePages`.
+- **Reports:** `PROJECT_getAuditReport`, `PROJECT_getAuditHistory`, `PROJECT_getAuditStatus`, `PROJECT_getCrawledPages`, `PROJECT_getIssuesByUrl`, `PROJECT_getAuditPagesByIssue`.
+
+### Backlinks (Project-attached, ~10 tools)
+
+For monitoring user-owned backlinks (vs. crawling any domain via Data API).
+
+- **CRUD:** `PROJECT_listProjectBacklinks`, `PROJECT_addProjectBacklink`, `PROJECT_deleteProjectBacklinks`, `PROJECT_recheckProjectBacklinks`.
+- **Groups:** `PROJECT_listBacklinkGroups`, `PROJECT_createBacklinkGroup`, `PROJECT_renameBacklinkGroup`, `PROJECT_deleteBacklinkGroup`, `PROJECT_moveBacklinksToGroup`.
+- **GSC import:** `PROJECT_runBacklinkGscImport`, `PROJECT_getBacklinkGscImportStatus`, `PROJECT_updateBacklinkImportSettings`.
+- **Stats:** `PROJECT_getBacklinkStats`, `PROJECT_getFoundLinks`.
+- **Disavow:** `PROJECT_listDisavowedBacklinks`, `PROJECT_addDisavowedBacklinks`, `PROJECT_deleteDisavowedBacklink`.
+
+### AIRT — AI Result Tracker (~10 tools)
+
+- **Prompts:** `PROJECT_listPrompts`, `PROJECT_addPrompts`, `PROJECT_deletePrompts`, `PROJECT_transferPrompts`.
+- **Prompt groups:** `PROJECT_listPromptGroups`, `PROJECT_createPromptGroup`, `PROJECT_updatePromptGroup`, `PROJECT_deletePromptGroup`, `PROJECT_deleteAllPromptsInGroup`, `PROJECT_movePromptsToGroup`, `PROJECT_changePromptGroupOrder`.
+- **LLM engines:** `PROJECT_listLlmEngines`, `PROJECT_getLlmEngine`, `PROJECT_createLlmEngine`, `PROJECT_updateLlmEngine`, `PROJECT_deleteLlmEngine`.
+- **Status & results:** `PROJECT_getLlmStatus`, `PROJECT_getLlmStatistics`, `PROJECT_getPromptAnswer`, `PROJECT_getPromptsRankings`.
+
+### Marketing plan (~3 tools)
+
+- `PROJECT_getMarketingPlan`, `PROJECT_addPlanTask`, `PROJECT_updatePlanTask`, `PROJECT_setPlanTaskStatus`, `PROJECT_deletePlanTask`.
+
+### Sub-accounts (~5 tools)
+
+- `PROJECT_listSubAccounts`, `PROJECT_createSubAccount`, `PROJECT_updateSubAccount`, `PROJECT_deleteSubAccount`, `PROJECT_getSubAccountDetails`.
+
+### Account & profile (~3 tools)
+
+- `PROJECT_getUserProfile`, `PROJECT_getAdsStats`.
+
+## ID resolution — the lookup-first pattern
+
+Most Project API operations need an ID. The skill should call the appropriate `*list*` or `*available*` tool first when the user didn't supply it.
+
+| User said… | Lookup tool | Returns | Pass to |
+|---|---|---|---|
+| "for my project on acme.com" | `PROJECT_listProjects` | List of projects + `project_id` | `project_id` to any per-project tool |
+| "track in the US" | (none — pass `country_code: "us"` directly) | — | `PROJECT_addSearchEngine` resolves automatically |
+| "track in Catalonia" | `PROJECT_getAvailableSearchEngines` | `id` for regional engine | `search_engine_id` to `PROJECT_addSearchEngine` |
+| "in Spanish" | `PROJECT_getGoogleLanguages` | Language code list | `language_code` to rank-tracking tools |
+| "in Barcelona" | `PROJECT_getAvailableRegions` | Region records with verbatim `name` | `region_name` to rank-tracking tools (use exact name — abbreviations rejected) |
+| "for keyword group X" | `PROJECT_listKeywordGroups` | Group IDs + names | `group_id` to `PROJECT_moveKeywordsToGroup` etc. |
+| "for our backlink group X" | `PROJECT_listBacklinkGroups` | Group IDs + names | `group_id` to backlink group tools |
+| "for AIRT prompt group X" | `PROJECT_listPromptGroups` | Group IDs + names | `group_id` to prompt group tools |
+| "for SERP in {city}" | `DATA_getSerpLocations` | Locations + codes | `location` to SERP tools |
+| "audit X" | `DATA_listAudits` / `PROJECT_listAudits` | Audit IDs | `audit_id` to report/recheck/delete |
+
+## Quick decision tree
+
+```
+"I want to research a domain I don't own"
+  → Data API
+    backlinks → DATA_getBacklinks*
+    keywords → DATA_getDomainKeywords / getDomainOverviewWorldwide
+    competitors → DATA_getDomainCompetitors
+    SERP for a keyword → DATA_getSerpResults / SerpTask
+    one-off audit → DATA_createStandardAudit
+    LLM visibility → DATA_getAiSearch*
+
+"I want to track/manage state on my own SE Ranking projects"
+  → Project API (needs Business/Enterprise plan)
+    create project → PROJECT_createProject
+    add keywords to track → PROJECT_addKeywords (after PROJECT_addSearchEngine)
+    daily ranks → PROJECT_runPositionCheck / PROJECT_getPositionHistory
+    project audit → PROJECT_createAudit
+    backlink monitoring → PROJECT_addProjectBacklink (with PROJECT_runBacklinkGscImport for bulk)
+    AIRT prompts → PROJECT_addPrompts (with PROJECT_createLlmEngine if a custom engine)
+    competitors → PROJECT_addCompetitor + PROJECT_getCompetitorPositions
+
+"I want to integrate SE Ranking into another tool"
+  → Both, usually
+    e.g., "weekly client report"
+      use PROJECT_getPositionHistory + DATA_getDomainCompetitors + DATA_getBacklinksSummary
+      pipe into Looker / Sheets / your dashboard
+```
+
+## Built-in MCP prompts (server-shipped recipes)
+
+The MCP server ships 5 built-in prompts (via the `prompts/list` capability) — encoded recommended tool sequences for common workflows. **Prefer these when the user's ask matches**:
+
+| Prompt | What it does | Args |
+|---|---|---|
+| `serp-analysis` | Compare SERPs across two locations for a keyword | `keyword`, `location1`, `location2`, optional `language`, optional `device` |
+| `backlink-gap` | Find backlink opportunities vs. competitors | `my_domain`, `competitors` (comma-separated), optional `min_domain_trust` |
+| `domain-traffic-competitors` | Traffic + top competitors for a domain | `domain` |
+| `keyword-clusters` | Build intent-grouped keyword clusters | `market`, `seed_keywords` |
+| `ai-share-of-voice` | LLM-engine visibility vs. competitors | `domain`, `competitors`, optional `country`, `llm_engines` |
+
+These prompts are accessible via any spec-compliant MCP client. In Claude Code: `/mcp` shows them; calling `mcp__claude_ai_SE_Ranking__<prompt-name>` (varies by client) executes.