optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/seranking-seo/skills/seo-api/references/rate-limits-and-credits.md

@@ -0,0 +1,235 @@
+# Rate Limits & Credits
+
+Everything the `seo-api` skill needs to forecast cost and pace requests against the Data API and Project API.
+
+## Rate limits
+
+**Per API key, not per IP.** All threads, workers, and servers sharing one key contribute to the same RPS budget. For production fan-outs, mint multiple keys via the API Dashboard.
+
+| API | Standard limit | Trial accounts |
+|---|---|---|
+| Data API | **10 requests per second** | 1 RPS (can be raised on request — email api@seranking.com) |
+| Project API | **5 requests per second** | 1 RPS (same path to raise) |
+
+**Async operations.** Endpoints like `/backlinks/export` create a task; subsequent polls of `*ExportStatus` count against the same RPS budget (but cost 0 credits).
+
+**Custom limits.** Production workloads needing higher throughput: contact `api@seranking.com`. Custom plans are available.
+
+## Handling 429 — exponential backoff with jitter
+
+```python
+import random, time, requests
+
+def call(url, headers, max_attempts=5):
+    delay = 1.0
+    for attempt in range(max_attempts):
+        r = requests.get(url, headers=headers)
+        if r.status_code != 429:
+            return r
+        jitter = random.uniform(-0.2, 0.2) * delay
+        time.sleep(delay + jitter)
+        delay *= 2
+    r.raise_for_status()
+```
+
+```typescript
+async function call(url: string, headers: HeadersInit, maxAttempts = 5): Promise<Response> {
+  let delay = 1000;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const r = await fetch(url, { headers });
+    if (r.status !== 429) return r;
+    const jitter = (Math.random() * 0.4 - 0.2) * delay;
+    await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+    delay *= 2;
+  }
+  throw new Error(`Rate-limited after ${maxAttempts} attempts`);
+}
+```
+
+**Why jitter matters.** Without it, multiple clients hitting the limit simultaneously synchronise their retries and re-hit the limit at the next interval — the thundering-herd problem. A ±20% randomisation spreads them out.
+
+**Simple delays (use with caution).** Because the API uses a rolling 1s window, a brief pause (200–500ms) is enough for occasional, isolated overages. But it doesn't survive bursty traffic — use exponential backoff for anything production.
+
+## Client-side throttling
+
+Better than reactive 429 handling: proactively pace requests to stay under the limit.
+
+```python
+import time
+from collections import deque
+
+class RateLimiter:
+    def __init__(self, rps: int):
+        self.rps = rps
+        self.calls = deque()
+
+    def acquire(self):
+        now = time.monotonic()
+        while self.calls and self.calls[0] < now - 1.0:
+            self.calls.popleft()
+        if len(self.calls) >= self.rps:
+            time.sleep(1.0 - (now - self.calls[0]))
+        self.calls.append(time.monotonic())
+
+limiter = RateLimiter(rps=10)
+for url in urls:
+    limiter.acquire()
+    call(url, headers)
+```
+
+## Credit system (Data API)
+
+Pay-as-you-go. Plans start at 1 million credits.
+
+### Two billing models
+
+1. **Cost per record** — credits charged per row returned. Example: `/backlinks/summary` at 100 credits/record, request 250 domains → 25,000 credits.
+2. **Cost per request** — flat fee per successful call regardless of payload size. Example: `/keywords/research` at 5 credits/request, 1000 keywords returned → still 5 credits.
+
+**Failed requests are free.** 4xx and 5xx never consume credits. Don't over-engineer error retries to "save credits".
+
+### Reading current balance
+
+```bash
+curl -X GET 'https://api.seranking.com/v1/account/subscription' \
+  -H 'Authorization: Token YOUR_API_KEY'
+```
+
+Or via MCP: `DATA_getCreditBalance` (0 credits, returns `units_left`).
+
+Response shape:
+```json
+{
+  "subscription_info": {
+    "status": "active",
+    "start_date": "2026-01-18 14:20:02",
+    "expiration_date": "2027-01-18 14:20:02",
+    "units_limit": 5000000,
+    "units_left": 4975033
+  }
+}
+```
+
+### Forecasting
+
+Before running a large workflow:
+
+1. List every API call.
+2. Multiply by per-call cost (see canonical table at <https://seranking.com/api/data/getting-started/#unit-costs>, or check each MCP tool's own description for the per-tool figure).
+3. Sum.
+4. Compare against `units_left`.
+
+**Worked example.** Pull backlink summaries for 250 domains + full export for one:
+
+| Call | Records | Per-record cost | Total |
+|---|---|---|---|
+| `/backlinks/summary` | 250 | 100 credits | 25,000 |
+| `/backlinks/export` (task creation) | 50,000 (links in target domain) | 1 credit | 50,000 |
+| `/backlinks/export/status` (poll 2×) | 2 | 0 credits/request | 0 |
+| **Total** | | | **75,000 credits** |
+
+### Insufficient credits — 403
+
+```json
+{
+  "error": {
+    "code": 403,
+    "message": "Insufficient funds",
+    "description": "Your current credit balance is too low to process this request."
+  }
+}
+```
+
+No partial billing — the entire request is rejected. Top up at the API Dashboard or contact `api@seranking.com` for overage billing.
+
+## Plan limits (Project API)
+
+The Project API doesn't use credits. It consumes the same limits as the SE Ranking web platform.
+
+| Action | Limit consumed | When |
+|---|---|---|
+| `PROJECT_createProject` | 1 Site | On creation |
+| `PROJECT_addKeywords` | N Keywords | Each new keyword tracked |
+| `PROJECT_runPositionCheck` | (free — uses tracking schedule) | — |
+| `PROJECT_addAuditSourcePages` + audit run | N Audit Pages | Per page crawled |
+| `PROJECT_createAudit` (advanced) | Audit Pages × pages | Per crawl |
+| `PROJECT_addPrompts` | N AIRT Prompts | Per prompt added to AIRT |
+| `PROJECT_addCompetitor` | (free) | — |
+| `PROJECT_addProjectBacklink` | (free — uses Backlinks tier) | — |
+
+**Read the user's plan limits before mutating.** `PROJECT_getUserProfile` returns the current plan tier and remaining quota. If the integration would push a limit over, surface upfront and ask whether to proceed or downsize.
+
+### Insufficient plan limits
+
+```json
+{
+  "error": {
+    "code": 403,
+    "message": "Limit reached",
+    "description": "Cannot add 50 keywords — you have 32 keywords remaining on the Pro plan."
+  }
+}
+```
+
+Fix paths:
+- Upgrade plan: <https://seranking.com/subscription.html>.
+- Free up quota: delete unused projects, keywords, AIRT prompts via the matching `PROJECT_delete*` tool.
+
+## Per-endpoint cost cheat-sheet
+
+Credit costs are **not** carried in the MCP tool descriptions — the canonical source is the per-endpoint pages on `seranking.com/api/data/*` and the unit-costs table at <https://seranking.com/api/data/getting-started/#unit-costs>. Always confirm there before a large run; SE Ranking updates costs periodically.
+
+**Verified against the docs (2026-05-22):**
+
+| Endpoint | MCP tool | Cost |
+|---|---|---|
+| Account subscription | `DATA_getSubscription` | 0 |
+| Credit balance | `DATA_getCreditBalance` | 0 |
+| Domain overview (worldwide) | `DATA_getDomainOverviewWorldwide` | 100 / request |
+| Domain overview (regional) | `DATA_getDomainOverviewDatabases` | 100 / request |
+| Domain competitors | `DATA_getDomainCompetitors` | 100 / request (flat — *not* per-competitor) |
+| Backlinks summary | `DATA_getBacklinksSummary` | 100 / target |
+
+For any endpoint not in this table, read the **"Cost:"** line on its docs page before forecasting — do not guess a figure. Apply the two billing models described above: **per request** (flat fee per call — most overview / summary / competitor endpoints) and **per record** (one charge per row — list and export endpoints; e.g. `DATA_exportBacklinksData` charges per backlink record, `DATA_getDomainKeywords` per keyword returned). When unsure, run the smallest possible request first and read the actual charge against the docs.
+
+## Combined rate-limit + credit safety pattern
+
+The end-to-end shape for any production integration:
+
+```python
+import time, random, requests
+
+API_KEY = os.environ["SERANKING_API_KEY"]
+HEADERS = {"Authorization": f"Token {API_KEY}"}
+BASE = "https://api.seranking.com/v1"
+
+class SERankingClient:
+    def __init__(self, rps=10):
+        self.rps = rps
+        self.calls = deque()
+
+    def _throttle(self):
+        now = time.monotonic()
+        while self.calls and self.calls[0] < now - 1.0:
+            self.calls.popleft()
+        if len(self.calls) >= self.rps:
+            time.sleep(1.0 - (now - self.calls[0]))
+        self.calls.append(time.monotonic())
+
+    def get(self, path, params=None, max_attempts=5):
+        delay = 1.0
+        for attempt in range(max_attempts):
+            self._throttle()
+            r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params)
+            if r.status_code == 429:
+                time.sleep(delay + random.uniform(-0.2, 0.2) * delay)
+                delay *= 2
+                continue
+            if r.status_code == 403 and "Insufficient funds" in r.text:
+                raise RuntimeError("Out of credits — top up before retrying.")
+            r.raise_for_status()
+            return r.json()
+        raise RuntimeError(f"Rate-limited after {max_attempts} attempts on {path}")
+```
+
+This handles the common cases: rate-limit pacing, exponential backoff with jitter, terminal 403, transient 5xx. Tune `rps` to match the API (5 for Project, 10 for Data).

package/skills/optbrew/modules/seranking-seo/skills/seo-competitor-gap-analysis/GUIDE.md

@@ -0,0 +1,117 @@
+> Example output: examples/seo-competitor-gap-analysis-wix-com-20260514/REPORT.md (upstream-only reference; route through optbrew)
+
+# Competitor Gap Analysis
+
+Identify the specific keywords your competitors rank for in the top 20 that your domain does not, ranked by commercial value and realistic capture difficulty.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- User provides: (a) target domain, (b) 3 to 5 competitor domains (or ask the skill to auto-discover them), (c) market country (default: `us`), and optionally filters (min volume, max KD, intent).
+
+## Process
+
+1. **Validate or discover competitors** `DATA_getDomainCompetitors`
+   - If the user did not provide competitors, pull the top 5 organic competitors for the target in the target market.
+   - Surface the list to the user and ask them to confirm or override before proceeding.
+   - **Note:** the upstream API does not support `limit`/`offset`, so this call returns the full set (~60KB for popular domains) and the MCP harness writes it to a file. Read that file path, parse the `{data: [...]}` JSON, sort by `common_keywords` desc, and take the top 5.
+
+2. **Pull competitor keyword sets** `DATA_getDomainKeywords`
+   - For each competitor, pull keywords where they rank in the top 20 of the target country.
+   - Save per-competitor lists.
+
+3. **Pull target keyword set** `DATA_getDomainKeywords`
+   - For the target domain, pull all ranking keywords in the target country (any position).
+   - This is the exclusion set.
+
+4. **Compute the gap** `DATA_getDomainKeywordsComparison` (cross-check)
+   - Keywords ranked by at least one competitor in the top 20 but not ranked by the target domain at all.
+   - Use the comparison endpoint as a cross-check.
+
+5. **Filter and segment**
+   - Apply user-specified filters on volume, KD, and intent.
+   - Segment by intent: informational, commercial, transactional, navigational.
+   - Segment by competition: how many of the N competitors rank for each gap keyword.
+
+6. **Score and prioritise**
+   - Score each gap keyword: traffic potential (volume × CTR model) + intent weighting + inverse KD.
+   - Surface the top 50 opportunities with reasoning per keyword.
+
+7. **Map to content actions**
+   - For each top opportunity, recommend: new article, expand existing page, refresh existing page, programmatic template.
+   - Flag quick wins: competitors rank with thin content (detected by URL pattern and content-length heuristics).
+
+## Output format
+
+Create a folder `seo-competitor-gap-analysis-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-competitor-gap-analysis-{target-slug}-{YYYYMMDD}/
+├── REPORT.md                                (synthesised report — primary deliverable)
+├── gaps.csv                                 (full gap list — load-bearing CSV the writers/planners paste into briefs)
+└── evidence/
+    ├── 01-competitors.md                    (competitor list / discovery — raw step output)
+    ├── 02-competitor-keywords-{domain}.md   (one per competitor — raw step output)
+    ├── 03-target-keywords.md                (target's existing ranking set — raw step output)
+    └── 04-gap-raw.md                        (human-readable full gap list before filtering — raw step output)
+```
+
+Top-level: `REPORT.md` + `gaps.csv`. The numbered step files preserve the raw API outputs in `evidence/` for reproducibility.
+
+`REPORT.md` follows this shape:
+
+```markdown
+# Competitor Gap: {target}
+Market: {country}
+Competitors analysed: {list}
+
+## Summary
+- Competitor keywords in top 20: {n}
+- Target keywords overall: {n}
+- Gap keywords (opportunities): {n}
+- Gap traffic potential: ~{n}/mo
+
+## Top 50 opportunities
+
+### Informational intent
+| # | Keyword | Volume | KD | Competitors ranking | Action | Score |
+|---|---|---|---|---|---|---|
+| 1 | {kw} | {n} | {n} | {3 of 5} | New article | {score} |
+| 2 | ... | ... | ... | ... | ... | ... |
+
+### Commercial intent
+| # | Keyword | Volume | KD | Competitors ranking | Action | Score |
+|---|---|---|---|---|---|---|
+...
+
+### Transactional intent
+...
+
+## Quick wins (top 10)
+Keywords where competitors rank in positions 5 to 20 with thin content, low DT, or old dates.
+
+| # | Keyword | Weakest competitor position | Suggested angle |
+|---|---|---|---|
+| 1 | {kw} | example.com at #14 (2022 article, 800 words) | Fresh, comprehensive guide |
+
+## Recommended next steps
+1. Run `content-brief` on the top 3 opportunities to generate writer-ready briefs.
+2. Run `keyword-cluster-planner` on the full gap list to build a sequencing plan.
+3. Add the gap keywords to an SE Ranking project for rank tracking once content ships.
+
+## Files
+- gaps.csv: full gap list for spreadsheet analysis
+- evidence/04-gap-raw.md: human-readable full gap list before filtering
+```
+
+`gaps.csv` columns:
+`keyword,volume,kd,cpc,intent,competitors_ranking,top_competitor_position,target_position,action,score`
+
+## Tips
+
+- Data API rate limit: 10 requests per second. For large sites, `DATA_getDomainKeywords` may paginate heavily; set a ceiling (e.g., top 1,000 keywords per domain) unless the user explicitly asks for the full set.
+- Call `DATA_getCreditBalance` before running. A full pass on 10 seeds typically consumes 30–80 credits; 20 seeds can exceed 150.
+- The `competitors_ranking` count is the best signal of realism. Keywords ranked by 4 of 5 competitors are validated opportunities; keywords ranked by only 1 may be noise.
+- Do not recommend capturing branded competitor keywords unless the user explicitly asks. Pivoting to compete on "competitor brand review" is a viable strategy but only if the user opts in.
+- When many gap keywords cluster around a theme, recommend a hub page plus cluster rather than 50 individual articles.
+- Chain this skill with `content-brief` and `keyword-cluster-planner` naturally. Mention them in the Recommended next steps section of the output.

package/skills/optbrew/modules/seranking-seo/skills/seo-content-audit/GUIDE.md

@@ -0,0 +1,155 @@
+> Example output: examples/seo-content-audit-stripe-rate-limiters-20260514/VERDICT.md (upstream-only reference; route through optbrew)
+
+# Content Quality Audit
+
+Score an existing piece of content against modern E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) and CITE (Clear answer, Include primary stats, Timestamp, Entity authority) rubrics. Surface veto items that block publication regardless of overall score. Produce a clear publish / publish-with-fixes / no-publish verdict with the top 5 fixes.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- Claude's `WebFetch` tool available.
+- User provides: (a) the URL of an existing piece of content (or pasted content + intended URL), (b) target keyword the content is meant to rank for. Optional: target country (default `us`).
+
+## Process
+
+1. **Fetch content** `WebFetch` (always) + `mcp__firecrawl-mcp__firecrawl_scrape` (when available)
+   - **Validate target & preflight.** See `skills/seo-firecrawl/references/preflight.md` for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:
+     - Estimated SE Ranking cost for this skill: ~10–15 credits typical (AIO context + AIO prompt sampling for the target keyword + audited URL).
+     - Firecrawl: optional with WebFetch fallback, 1 Firecrawl credit per URL audited (default cap 50 URLs, hard cap 200). Surface the projected Firecrawl credit count before continuing. Pass `--no-firecrawl` to force WebFetch-only inspection (lower-confidence veto checks; see step 4 caveat).
+     - Google APIs: tier 2 (GA4 available) unlocks step 3b (GA4 organic traffic on the audited URL) after the AIO context step. See `skills/seo-google/references/cross-skill-integration.md` § "seo-content-audit" for the full recipe.
+   - **WebFetch first** (free, instant): pull the markdown for word count, H-tag hierarchy, source citations (links to authorities, numbered references), images, tables, code blocks, comment thread.
+   - **Page-type detection.** From the URL pattern, H1 phrasing, and JSON-LD `@type`, classify the page as one of: ultimate guide / pillar, how-to, listicle / best-of, comparison (X vs Y), explainer, review (single product), landing page (commercial). Look up the corresponding word-count floor from `references/core-eeat.md` → "Word-count floors by page type". Surface the detected type, the applied floor, and the actual word count in `evidence/01-content-snapshot.md`. If the actual word count is materially below the floor, flag it for the depth E-E-A-T items (auto ✗ unless the auditor justifies the exception).
+   - **Firecrawl second** — recovers what WebFetch's markdown loses:
+     - From `metadata`: canonical URL, robots, lang, `og:title`.
+     - From the returned `html`: every `<script type="application/ld+json">` block. Parse for `Article` / `BlogPosting` schema and extract `author` (name, `@type: Person`, optional `url` + `sameAs`), `datePublished` / `dateModified` (ISO 8601), `publisher`, `mainEntityOfPage`. Detect `Person` schema standalone if present.
+     - DOM-level byline detection: locate the structural byline (`<a rel="author">`, `<meta name="author">`, `<span class="byline">`, `[itemprop="author"]`). Distinguish a real byline element from prose mentions ("Written by Jane in collaboration..." in body text is not a byline; `<a rel="author">Jane Doe</a>` is).
+   - **If Firecrawl unavailable:** WebFetch portion runs unchanged. Mark schema-type detection and structural byline detection as `(skipped — Firecrawl required)` in `evidence/01-content-snapshot.md`. Step 4's veto checks #1 and #4 fall back to prose-level inspection (less reliable) — surface that caveat in `VERDICT.md`.
+
+2. **AIO context** `DATA_getAiOverview` and `DATA_getAiOverviewLeaderboard`
+   - For the target keyword: is there an AIO?
+   - Who is cited in the AIO?
+   - Is the candidate URL cited?
+   - What patterns characterise the cited sources (publication tier, freshness, structure)?
+
+3. **AIO prompt sampling** `DATA_getAiPromptsByTarget`
+   - Sample LLM prompts where the target URL's domain appears as a source.
+   - Cross-reference with the candidate URL — does it show up in any sampled prompts?
+
+3b. **GA4 organic traffic on the audited URL** *(only if google-api.json is present, tier ≥ 2)*
+   - Replaces the implicit traffic estimation with actual measured organic sessions for the audited URL.
+   - Pull the top organic landing pages (last 28 days):
+     `upstream script excluded; use optbrew capability routing top-pages --days 28 --json`
+   - Filter the result client-side for the audited URL's path. Surface in `VERDICT.md` "## Snapshot" alongside the existing AIO citation cross-check:
+     - GA4 organic last 28d: `{sessions} sessions / {users} users / avg engagement {n}s`
+     - If the URL doesn't appear in the top-100 organic landing pages: "GA4: not in top-100 organic landing pages last 28d — low or zero traffic."
+   - **This is a signal, not a veto.** Low GA4 traffic on a YMYL page with high E-E-A-T is informative ("we're not earning the visibility our content quality should support") but doesn't change the publish decision.
+   - See `skills/seo-google/references/cross-skill-integration.md` § "seo-content-audit" for the full recipe.
+
+4. **Score E-E-A-T** using `references/core-eeat.md`
+   - 60-item rubric across 4 dimensions (15 items each).
+   - Per-item: yes/no/partial. Compute dimension scores (0–100% each).
+   - Score the 8-item **AI-content markers** subsection (see references/core-eeat.md → "AI-content markers"). Mark each fired/not-fired.
+   - Apply 4 veto checks. Any veto = no-publish.
+     1. Anonymous author on YMYL topic. (High-confidence with Firecrawl-recovered author schema + DOM byline; medium-confidence with prose-only inspection.)
+     2. Factual claims with no sources cited.
+     3. Undisclosed affiliate / sponsored relationships.
+     4. AI-generated YMYL content with no human-review markers (≥4 AI-content markers fired AND YMYL topic AND no editor byline / "reviewed by" credit / "last reviewed" or "fact-checked on" date). The "editor byline / reviewed by" check uses Firecrawl-recovered DOM byline + Article-schema `author` when available; falls back to prose-level pattern match if Firecrawl is absent (lower confidence — note in `VERDICT.md`).
+
+5. **Score CITE** using `references/cite.md`
+   - 30-item CITE rubric (Clear answer in 1st 200 words, Include primary stats, Timestamp freshness, Entity authority).
+   - Per-item: yes/no/partial. Compute dimension scores.
+   - Apply 3 veto checks (no answer in first 300 words / no datestamp on time-sensitive content / no entity disambiguation for proper-noun queries).
+
+6. **Cross-check against AIO winners**
+   - For the patterns characteristic of cited sources (from step 2), evaluate the candidate against each: does it have what the cited sources have?
+   - Surface specific gaps.
+
+7. **Synthesise verdict** using `templates/verdict.md`
+   - **Publish:** E-E-A-T ≥ 75%, CITE ≥ 70%, no vetoes triggered.
+   - **Publish with fixes:** E-E-A-T 60–74% OR CITE 55–69%, no vetoes. Top 5 fixes specified.
+   - **No publish:** any veto triggered, OR E-E-A-T < 60%, OR CITE < 55%. Substantial rewrite needed.
+
+## Output format
+
+Create a folder `seo-content-audit-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-content-audit-{target-slug}-{YYYYMMDD}/
+├── VERDICT.md                       (publish / publish-with-fixes / no-publish — primary deliverable; inlines content snapshot + AIO context)
+├── 03-eeat-scoring.md               (60-item rubric scored — load-bearing reference an editor consults item-by-item)
+├── 04-cite-scoring.md               (30-item rubric scored — load-bearing reference)
+├── 05-aio-winner-comparison.md      (gap vs cited sources — must remain top-level; live AIO competitive evidence per EVAL_RESULT_v2.md §9)
+└── evidence/
+    ├── 01-content-snapshot.md       (HTML extracts + page metadata — raw step output)
+    └── 02-aio-context.md            (AIO presence, citations, patterns — raw step output)
+```
+
+Step files 01 + 02 are inlined as a "Snapshot" / "AIO context" section in `VERDICT.md`; the copies in `evidence/` preserve raw step output. `03-eeat-scoring.md`, `04-cite-scoring.md`, and `05-aio-winner-comparison.md` stay at top level — editors consult the rubric scoring detail directly, and the AIO winner comparison is the live competitive evidence the rubric verdict rests on.
+
+`VERDICT.md` follows this shape (also see `templates/verdict.md`):
+
+```markdown
+# Content Audit: {URL or title}
+
+> Audited {YYYY-MM-DD} · Target keyword: "{keyword}" · Country: {country}
+
+## Verdict: {PUBLISH | PUBLISH WITH FIXES | NO PUBLISH}
+
+{One sentence summary of why}
+
+## Scores
+
+| Dimension | Score | Threshold | Status |
+|---|---|---|---|
+| Experience | {n}% | 75% | {✓/✗} |
+| Expertise | {n}% | 75% | {✓/✗} |
+| Authoritativeness | {n}% | 75% | {✓/✗} |
+| Trustworthiness | {n}% | 75% | {✓/✗} |
+| **E-E-A-T composite** | {n}% | 75% | {✓/✗} |
+| Clear answer | {n}% | 70% | {✓/✗} |
+| Include stats | {n}% | 70% | {✓/✗} |
+| Timestamp | {n}% | 70% | {✓/✗} |
+| Entity authority | {n}% | 70% | {✓/✗} |
+| **CITE composite** | {n}% | 70% | {✓/✗} |
+
+## Veto checks
+
+- Anonymous author on YMYL: {triggered / not triggered}
+- Unsourced factual claims: {triggered / not triggered}
+- Undisclosed affiliate / sponsored: {triggered / not triggered}
+- AI-generated YMYL with no human review: {triggered / not triggered} ({n}/8 AI-content markers fired)
+- ...
+
+## AI Search readiness
+- AIO present for "{keyword}": {yes/no}
+- Top citation patterns: {list}
+- Candidate URL cited in any sampled AIO: {yes/no}
+- Gap vs cited sources: {bulleted gaps}
+
+## Snapshot (measured)
+- GA4 organic last 28d: {sessions} sessions / {users} users / avg engagement {n}s  *(or `not in top-100` / `not configured (Tier 2 required)`)*
+
+## Top 5 fixes
+
+1. {Specific fix linked to a low-scored item or veto}
+2. ...
+5. ...
+
+## Detailed scoring
+
+See:
+- 03-eeat-scoring.md (item-by-item E-E-A-T)
+- 04-cite-scoring.md (item-by-item CITE)
+- 05-aio-winner-comparison.md (gap analysis)
+```
+
+## Tips
+
+- Respect rate limit. AIO + AIO-prompts queries are ~5–10 calls; plenty of headroom.
+- Call `DATA_getCreditBalance` before running. ~10–15 SE Ranking credits typical, plus 1 Firecrawl credit per URL audited when Firecrawl is installed (default cap 50 URLs).
+- The thresholds (75% E-E-A-T, 70% CITE) are starting points. Tune per domain — a YMYL site (medical, financial) should require higher (85%/80%); a general-interest blog can run lower (65%/60%).
+- The veto checks are not negotiable. A piece with anonymous authorship on a YMYL topic doesn't pass regardless of score.
+- For pieces that score "publish with fixes," the top-5 list is the deliverable. Hand it to the writer; re-audit after fixes.
+- Pair with `seo-content-brief` for the new-article counterpart: this skill audits existing content, content-brief produces new content.
+- Pair with `seo-sxo` if the page has technical/page-type issues — that's a different diagnosis.
+- The 60-item E-E-A-T rubric and 30-item CITE rubric are in `references/`. They are opinionated — adjust for your domain's editorial standards.

package/skills/optbrew/modules/seranking-seo/skills/seo-content-audit/references/cite.md

@@ -0,0 +1,84 @@
+# CITE rubric (30 items)
+
+CITE = Clear answer, Include primary stats, Timestamp freshness, Entity authority. Tuned for AI-search citation readiness — passages from pages with high CITE scores are the ones LLMs cite.
+
+## Veto items (any one triggers automatic NO PUBLISH)
+
+1. **No clear answer in the first 300 words.** LLMs scan early paragraphs; if the answer isn't there, the page won't be cited.
+2. **No datestamp on time-sensitive content.** "Best X 2024" published in 2026 with no last-updated indicator gets passed over.
+3. **No entity disambiguation for proper-noun queries.** A page about "Apple" that doesn't specify whether it's Apple Inc. (computers) or Apple Corp (Beatles) loses to clearer pages.
+
+---
+
+## 1. Clear answer (8 items)
+
+The answer is findable, fast, and direct.
+
+1. The primary question / topic of the piece is answered in the first 200 words.
+2. The first paragraph is ≤ 60 words and stands alone as a TL;DR.
+3. The answer is stated in declarative sentences, not buried in prose ("X is …", not "many people wonder whether X might be…").
+4. Headings preview the answer ("How long does X take?" → "X takes 4–6 weeks", not "Let's explore the timeline").
+5. Lists, tables, or step blocks present the answer in scannable form where applicable.
+6. Numbers, dates, and named entities appear in the answer (specifics that LLMs can extract).
+7. The answer is followed by supporting context, not the other way round.
+8. No clickbait deferral ("read on to find out…"). The answer is given, then explained.
+
+## 2. Include primary stats (8 items)
+
+The piece references concrete data, with attribution.
+
+1. At least one statistic, percentage, or number cited in the first half.
+2. Sources are linked inline next to the stat (not a footnote pile at the end).
+3. Sources are primary (the original study, government data, the company's own report) — not aggregator sites.
+4. Date of the data is stated near the stat ("per the 2025 X report").
+5. Multiple stats triangulate the same claim where possible (one source, then a corroborating source).
+6. Methodology of cited data is briefly contextualised (sample size, population, time window).
+7. Original data the author generated (survey, analysis, A/B test) is presented with methodology.
+8. Where data is contested, that's acknowledged; the piece doesn't cherry-pick.
+
+## 3. Timestamp freshness (7 items)
+
+The reader (and LLM) can tell when this piece is from.
+
+1. Original publish date visible on the page.
+2. Last-updated date visible (and different from publish date if updated).
+3. Year appears in title, URL, or first H1 if the topic is time-sensitive.
+4. Schema.org `datePublished` and `dateModified` populated correctly (ISO 8601).
+5. Time-sensitive claims (e.g., "current pricing," "best as of") have explicit dates.
+6. Updates log visible if the piece has been substantively revised.
+7. Old data points (>2 years) are flagged or replaced.
+
+## 4. Entity authority (7 items)
+
+Proper nouns, brands, people, places are disambiguated and authoritative.
+
+1. The primary entity (brand, product, person, place) is named with full identifier (e.g., "Apple Inc.", not just "Apple") at first mention.
+2. Wikipedia / Wikidata disambiguation is referenced or implicit through context.
+3. Schema.org markup includes the entity (`Organization`, `Person`, `Product`, `Place`) with `sameAs` links to authoritative profiles.
+4. Author byline links to a profile that establishes the author's expertise on this entity.
+5. Brand name is consistent across the piece (no informal abbreviations that confuse LLMs).
+6. Related entities are introduced with their own brief disambiguation (especially for B2B / niche topics).
+7. Citations include canonical entity references (e.g., DOI for papers, official URLs for products).
+
+---
+
+## How to score
+
+For each item, mark ✓ (1), ~ (0.5), or ✗ (0). Dimension score = sum / item-count × 100%. CITE composite = average of 4 dimensions.
+
+## Threshold
+
+- CITE composite ≥ 70% AND no veto = pass for citation-readiness.
+- 55–69% = "publish with fixes" — improve the lowest-scoring dimension first.
+- < 55% OR any veto = the piece will likely not be cited by AI search; substantial rework needed.
+
+## Why this matters in 2026
+
+LLM citation behavior consistently rewards passage-level extractability. Pages that score well on Clear answer + Include primary stats are the ones that get pulled into AIO, Perplexity, ChatGPT, and Gemini answers. CITE is a working approximation of what those models prefer; it's not a guarantee, but the correlation is strong.
+
+## Calibration tips
+
+- For news content, Timestamp freshness items 1, 2, 3, 5 should all be ✓ — undated news is dead.
+- For evergreen topics, Timestamp items 5–7 are about confirming the freshness window, not chasing dates.
+- For brand-monitoring content (where citation matters most), Entity authority should be ≥ 80%.
+- For commercial content, Include primary stats lifts pieces from "marketing-fluff" to "decision-grade" — invest here.