@clize/clize 0.28.1 → 0.29.0

package/skills/clize-seo/SKILL.md

@@ -1,28 +1,180 @@
 ---
 name: clize-seo
 description: >-
-  Read what `clize seo` returns and decide what to do about it. The commands give facts —
+  Run and read an SEO/GEO analysis with `clize seo`. The commands give facts —
   keyword metrics, who occupies a results page, your positions, where your traffic comes
-  from, what Search Console is showing you. This skill is the judgment layer: which keywords
-  are worth attacking at your authority level, what a results page is actually telling you,
-  where to place content so it gets found, how to write so AI engines can quote you, and how
-  to read a `seo check` without fooling yourself.
-  Triggers: "should I go after this keyword", "why aren't we ranking", "what does this SERP
-  mean", "read my seo check", "how do I get cited by ChatGPT", "write this page for AI search",
-  "where should I publish this", "is our SEO working".
+  from, what Search Console is showing you. This skill is the judgment layer: where the
+  keywords to test come from in the first place, how big and how expensive one analysis is,
+  what it has to deliver, which keywords are worth attacking at your authority level, what a
+  results page is actually telling you, where to place content so it gets found, how to write
+  so AI engines can quote you, and how to read a `seo check` without fooling yourself.
+  Triggers: "do keyword research", "find keyword opportunities", "should I go after this
+  keyword", "why aren't we ranking", "what does this SERP mean", "read my seo check", "how do
+  I get cited by ChatGPT", "write this page for AI search", "where should I publish this",
+  "is our SEO working".
 ---
 
-# Reading and acting on `clize seo`
+# Running and reading `clize seo`
 
 The commands are deliberately dumb: they compress facts, they never advise. `serp` will tell
 you a page is a `listicle_window`; it will not tell you to pitch those listicles. That call is
 yours, and this file is how to make it.
 
-Run `clize seo <cmd> --help` for exact flags. Everything below assumes you have the output.
+Run `clize seo <cmd> --help` for exact flags.
+
+**§1–§3 are how to run an analysis. §4–§8 are how to read what comes back.** If you are here
+because someone asked for "keyword opportunities", start at §1 — the most common failure of
+this product is not misreading a number, it is testing a keyword set that was never enumerated.
+
+---
+
+## 1. Where the seeds come from
+
+Every command except `competitors` is a **verifier**: you hand it words, it prices them. None
+of them will hand you a word you did not think of — except `competitors`, and the `newQueries`
+that come back from `check`. So the quality ceiling of the whole analysis is set before you
+spend a cent, by how the candidate list was built.
+
+**Enumerate the list. Do not recall it.** A list you produced by thinking hard about the
+product is a sample of your own memory, and it will be small, English-only, and biased toward
+words you already believed in.
+
+Measured case (kunavo.com, 2026-08-31). Round one: 19 keywords written down off the top of the
+head. Output: six thematic directions, zero rows anyone could start work on. Round two: a
+37-keyword matrix built by enumeration, same site, same day. Output included `openrouter
+alternative` at KD 1 with eight named roundups to pitch, a German pricing cluster, a Japanese
+error-message query at 2,900/month that turned out to be a pure-UGC wall (worth knowing — it
+killed a page that was about to be written), and two payment long-tails with no recorded volume
+that Search Console showed sitting at positions 4.5 and 8. **None of those exist in the 19.**
+
+### 1.1 Competitor teardown — the only command that produces words
+
+```
+clize seo competitors rival-one.com rival-two.com --limit 25
+```
+
+Two or three competitors × `--limit 25` is **50–75 candidates for about $0.09 a domain**, and
+they are pre-filtered by the only filter that matters: somebody is already ranking on them.
+Read `topKeywords[].keyword`, ignore their brand terms, keep everything else as a candidate.
+
+Pick competitors that are *your size or one step up*. Tearing down a category leader gives you
+their head terms, which you cannot have. Tearing down the site that ranks #4 on the queries you
+care about gives you the long tail that is actually reachable.
+
+Run this **first**, before you write down a single keyword of your own. It anchors the list in
+the market instead of in your head.
+
+### 1.2 Capability-surface enumeration — cross the axes, don't brainstorm
+
+Ask: *what can this product actually absorb a visitor for?* Then find the axes of that surface
+and take the cross-product. This is mechanical, and mechanical is the point.
+
+Common axes, and what a row looks like:
+
+| pattern | axis A | axis B | rows you get |
+| --- | --- | --- | --- |
+| Error-message capture | the exact strings your users see | each UI language you ship | `メッセージストリームでエラー`, `error in message stream` |
+| Payment/checkout tail | payment method (alipay, wechat, sepa, pix…) | your category noun | `alipay checkout api`, `pix payment link` |
+| Competitor displacement | each competitor brand | `alternative` / `vs <you>` / `pricing` / `review` | `openrouter alternative` |
+| New-thing window | model / API / spec names released in the last 90 days | `api`, `pricing`, `how to use` | `seedance api pricing` |
+| Locale × head term | your two or three head terms | each market you can serve | `de-DE` pricing cluster |
+
+Rules for the matrix:
+
+- **Write every cell, then filter.** Filtering while enumerating is just recalling again.
+- **Do the non-English cells.** They are where the low-competition rows are, and they are the
+  cells a memory-driven list always skips. Supported markets: `en-US, en-GB, en-CA, en-AU,
+  de-DE, fr-FR, es-ES, ja-JP` — anything else is a 400, so do not build rows you cannot price.
+- **Cells you can't serve are not candidates.** Ranking for a query you cannot answer is a
+  bounce, not a win.
+- 30–100 cells is a normal matrix. If you have twelve, you have not found your axes yet.
+
+### 1.3 Search Console feedback — free, and it does not repeat your bias
+
+`clize seo check` returns `gsc.newQueries`: queries Google is already showing you for that are
+not on your list. This is Google telling you what it thinks you are relevant for, which is
+information no amount of enumeration produces. It costs nothing. Fold it back into the matrix
+every round — it is the loop that makes the second analysis better than the first.
+
+---
+
+## 2. The shape of one analysis
+
+A cold start is a funnel, and the funnel has a known size and a known price.
+
+```
+30–100 candidates            (§1: competitor teardown + capability matrix)
+   → seo keywords            price the whole list in one batched call
+   → drop `wall`, keep `attackable` + interesting `no_volume`   (§5)
+   → 10–20 survivors
+   → seo serp each survivor  the SERP check that KD cannot replace  (§4)
+   → 10–20 rows in the deliverable table                            (§3)
+   → seo check --keywords <the survivors>   the baseline you measure against
+```
+
+### What it costs (measured, current version)
+
+| step | price | note |
+| --- | --- | --- |
+| `seo keywords`, 40 words | **~$0.10** | one batched call; per-word cost is negligible next to the fixed cost, so **always send the whole list at once** |
+| `seo competitors`, 3 domains × 25 | **~$0.28** | the cheapest words you will ever buy |
+| `seo serp`, one keyword | **~$0.02** | 10–20 of these is $0.20–0.40 |
+| `seo check` | **free**, plus ~$0.005/word to price words it has never priced | the metrics are reused for 30 days, so a re-check costs nothing |
+
+**A complete cold start runs about $0.70–1.00.** The default account cap is **$5/month**, so a
+careful analysis fits inside it four or five times over.
+
+Two behaviours follow, and both matter:
+
+- **Do not sample to save money.** Checking 12 of 40 keywords saves about six cents and costs
+  you the analysis. There is no version of this work where a smaller keyword batch is the right
+  economy. Price the whole list.
+- **Do not run blind into the wall either.** Every response carries a `budget` block
+  (`capUsd` / `spentThisMonth` / `remainingUsd`). Read it. If a call is refused with a 429, the
+  message names the exact flag to raise the cap — `--cap <usd>` on any `clize seo` command,
+  which both raises it and runs the command. Passing the flag *is* the consent; there is no
+  second confirmation, and there is no support ticket.
+- `check --budget` is a **per-domain** cap and is a different number from `--cap`. If you set a
+  domain budget above the account cap, `check` says so in `notes` — you would hit the account
+  wall first.
+
+> If you are carrying a mental model where `seo check` cost a dollar or two: that was the old
+> check, which scraped a full SERP for every tracked keyword every round. It doesn't any more.
+> Measurement is free; the exact-position scrape is now a deliberate single act (`seo serp`).
 
 ---
 
-## 1. Reading a results page (`seo serp`)
+## 3. What an analysis delivers
+
+**The deliverable is a table. Prose is the footnote, not the product.**
+
+A finished analysis is a keyword worksheet, one row per keyword, where every row can be handed
+to someone as a unit of work without further interpretation:
+
+| keyword | locale | sv | kd | serp verdict | intent | target page | format | priority |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| openrouter alternative | en-US | 1,300 | 1 | listicle_window | commercial | /compare/openrouter/ | comparison + pitch 8 roundups | P0 |
+| メッセージストリームでエラー | ja-JP | 2,900 | 0 | definition_wall (UGC) | informational | — | skip: Reddit/Zenn own it | — |
+
+- **`target page` and `format` are part of the row.** "This keyword is good" is not a unit of
+  work; "write /compare/openrouter/ as a comparison page and pitch these eight roundups" is.
+- **Rows you decided against stay in the table**, with the reason. That is what stops the next
+  session from re-buying the same keyword — and a `skip` row with a reason is a real finding.
+- **Write the table to a file.** Cross-session handoff is the file, not a retelling in chat. A
+  summary of a table is not a table.
+- **Narrative goes underneath as footnotes.** Two or three lines about what the pattern means.
+  Not six paragraphs of themes.
+
+### The pass/fail test
+
+If what you produced is a set of *directions* or *themes*, or the table has fewer than ten
+actionable rows, **the analysis failed and the fix is upstream, in §1**. Do not write it up.
+Go back and enumerate more cells. This is exactly what happened in round one of the kunavo
+dogfood: six well-argued themes, and not one row anybody could start on.
+
+---
+
+## 4. Reading a results page (`seo serp`)
 
 `verdict` compresses **who occupies the page**. Four values, and what each one means for
 whether you can get in:
@@ -49,6 +201,11 @@ keyword returns `official_wall`: three of the top five are Stripe's own properti
 difficulty score on a page nobody can enter is not an opportunity.** Never pick keywords from
 `band` alone; run `serp` on anything you are about to invest a page in.
 
+The reverse trap is just as expensive: a Japanese error-message query at 2,900/month and KD 0
+looks like a gift until `serp` shows the page is wall-to-wall Reddit, Zenn and Qiita threads.
+High volume plus zero difficulty plus a pure-UGC page means *the demand is real and it is not
+available to you*.
+
 ### The classifier does not judge intent — you do
 
 `ai agent deployment` returns `open`. Read the items and you find they are all about deploying
@@ -62,25 +219,40 @@ before committing to a keyword**, whatever the verdict says.
 An AI Overview sits above the organic results and answers the query in place. Position 3 under
 an AI Overview is worth much less than position 3 without one, and some of your impressions will
 never become clicks no matter what you do. Note it, factor it into expectations, and lean harder
-on being *quotable* (§4) than on being *ranked*.
+on being *quotable* (§7) than on being *ranked*.
 
 ---
 
-## 2. Picking keywords at your authority level (`seo keywords`)
+## 5. Picking keywords at your authority level (`seo keywords`)
 
-`band` is a mechanical bucket of keyword difficulty: `attackable` (<10), `stretch` (10–30),
-`wall` (>30), `no_volume`.
+`band` is a mechanical bucket: `attackable` (KD <10), `stretch` (10–30), `wall` (>30),
+`no_volume`, `no_data`.
 
 For a site with near-zero authority (new domain, few referring domains):
 
-- Attack `attackable` **that also pass the SERP check** (§1).
+- Attack `attackable` **that also pass the SERP check** (§4).
 - `stretch` is a 6–12 month bet; take at most one or two, and only if the SERP is a
   `listicle_window` you can parasitize meanwhile.
 - `wall` is not a plan. Skip it.
-- `no_volume` is not automatically worthless: a keyword with no recorded volume whose SERP is
-  already full of category roundups is a **pre-emergence** signal — the searches exist, the
-  keyword tools have not caught up. `email api for ai agents` had no volume and a
-  `listicle_window` with four roundups on it. That is a keyword worth an early page.
+
+### `no_data` and `no_volume` mean opposite things
+
+They used to be one value. They are not one thing:
+
+- **`no_data`** — we have no volume figure for this keyword. Either it was never priced, or it
+  was priced and the upstream has no row for it. It is an **absence of data** and it says
+  nothing whatsoever about demand. Never report it as "nobody searches for this."
+- **`no_volume`** — it *was* priced and the volume really is 0. That is a **signal**, and often
+  a valuable one: a keyword the tools have not caught up with. `email api for ai agents` had no
+  volume and a `listicle_window` with four roundups on it. On kunavo, two payment long-tails
+  came back at volume 0 and Search Console showed them at positions 4.5 and 8 with real
+  impressions — **people were already arriving on words the keyword tool scored as empty.**
+  That configuration has a name in `check` output: `pre_emergence` (§8).
+
+So: a `no_volume` row whose SERP is already full of category roundups is worth an early page.
+A `no_data` row is worth *pricing*, not deciding on.
+
+### `--ai` is a different unit
 
 `--ai` adds `aiSv`, the volume inside AI engines. **It is a different unit from `sv`.** Measured:
 `agent mail` is 5,400 on Google and 125 in AI engines; `ai email agent` is 140 and 5. Compare a
@@ -89,7 +261,7 @@ the same sentence as if they were the same quantity, and never add them.
 
 ---
 
-## 3. Where to place content
+## 6. Where to place content
 
 Priority order, most effective first for a low-authority site:
 
@@ -105,7 +277,7 @@ Priority order, most effective first for a low-authority site:
 
 ---
 
-## 4. Writing so AI engines can quote you
+## 7. Writing so AI engines can quote you
 
 Retrieval-augmented engines quote passages, not pages. What survives extraction:
 
@@ -121,21 +293,24 @@ Retrieval-augmented engines quote passages, not pages. What survives extraction:
 
 ---
 
-## 5. Reading a `seo check`
+## 8. Reading a `seo check`
 
 ### `rank`
 
-`rank.source` is always `"gsc"`: positions come from Search Console, free, and `check` makes no
-upstream calls at all. Read them accordingly.
+`rank.source` is always `"gsc"`: positions come from Search Console. Measurement makes no
+upstream calls; the only thing `check` may pay for is pricing keywords it has never priced.
 
 - `position` is the **impression-weighted average over `rank.window`**, not your rank at a moment.
   A 62.4 means "across the window, the average slot Google gave you was ~62". Two consequences:
-  a single good day barely moves it, and it is **not comparable** to a scraped SERP position
-  (or to any number a pre-0.28.0 check reported).
+  a single good day barely moves it, and it is **not comparable** to a scraped SERP position.
 - `delta` is **positive when you moved up** (the number got smaller), measured against
   `rank.prevWindow` — the equal-length window right before this one. `movers` shifted by 3+;
   anything smaller is averaging noise. `series` is weekly, newest first; weeks with no
   impressions are simply absent, so read the dates, not the spacing.
+- Each row also carries **`sv` and `kd` next to the Search Console numbers**. That is the whole
+  point of the row: demand and delivery side by side. A row with `sv: 27100` and `position: 74`
+  is a completely different situation from `sv: 0` and `position: 4.5`, and you should never
+  have to go find the second number somewhere else to see it.
 - `unseen` lists the keywords on your list that **Search Console did not see this window**.
   This is not "not ranking" — GSC only has a row once you get impressions. It is the honest
   statement "no data yet", and it costs nothing to say. **If you need one of these words' real
@@ -148,6 +323,35 @@ upstream calls at all. Read them accordingly.
 - **Competitor positions are not in `check`.** `--competitors` is remembered configuration only;
   a head-to-head on one keyword is `seo serp <keyword>`, where the whole page comes back at once.
 
+### `rank.signals` — the cross-source read, done for you
+
+`signals` is where the three sources are put side by side and labelled. It is **fact
+compression, not advice** — the same kind of thing as `serp`'s `verdict`. Every row carries the
+numbers the label was derived from (`sv`, `kd`, `position`, `impressions`, `clicks`), so you can
+overrule it. Three forms:
+
+| form | the configuration | how to read it |
+| --- | --- | --- |
+| `pre_emergence` | priced volume is **0**, and Search Console shows real impressions anyway | The demand exists and the keyword tools have not caught up. On a low-authority site this is the cheapest entry you will find: nobody is optimising for a keyword the tools score as empty. Write the page. |
+| `authority_limited` | many impressions, position 50+, **zero clicks** | Google is offering you the keyword surface and withholding the position. This is an authority bottleneck, not a content problem — **another page on the same theme will not move it.** Go do §6.1. |
+| `demand_no_surface` | real search volume, and Search Console gave you **no impressions at all** this window | The mirror image. Google is not even putting you on the shelf. That is a **discovery** question (is this reachable at your authority? what occupies it? → `seo serp`), not a measurement one. Running the measurement again will not answer it. |
+
+An empty `signals` array is not a failure; it means no keyword on your list is currently in one
+of these three shapes.
+
+There is deliberately **no** `data_conflict` form. That would need two independent position
+sources to disagree, and `check` has only one (Search Console). If you want the scraped-position
+comparison, that is an explicit `seo serp <keyword>` — and when the two disagree, believe
+Search Console: it is a 28-day average of what Google actually served, while a scrape is one
+personalised fetch of a rotating page.
+
+### `keywords.byBand`
+
+Counts **only keywords that have been priced**. Words on your list that have never been priced
+are excluded and the gap is stated in `notes` — an empty bucket is an honest empty, not a
+fabricated `no_volume`. `no_data` inside `byBand` means "we asked and the upstream has no row
+for it", which is a genuine finding about a very long-tail word.
+
 ### `traffic`
 
 - `ai` is always present, **including when it is all zeros — zero is the finding.** First
@@ -158,46 +362,40 @@ upstream calls at all. Read them accordingly.
 
 ### `gsc`
 
-- `newQueries` is the feedback loop closing: Google is telling you which queries it *considers*
-  you relevant for. Queries you never targeted showing real impressions are the most valuable
-  output of the whole command.
-- **Impressions with zero clicks at position 60–90 is not a content problem.** It means Google
-  is offering you the keyword surface and withholding the position. That is an authority
-  bottleneck; writing another page on the same theme will not move it. Go do §3.1.
+- `newQueries` is the feedback loop closing (§1.3): Google telling you which queries it
+  *considers* you relevant for. Queries you never targeted showing real impressions are the most
+  valuable output of the whole command. Fold them into the matrix.
 - `gsc: null` is not an error. Read `notes` — usually it means the service account has not been
   added to that property yet.
 
 ### The one rule that ties it together
 
-When `rank` puts you at ~70 on a keyword, `gsc` shows hundreds of impressions and almost no
-clicks on it, and `serp` says that page is a `listicle_window` — that is a complete, actionable
+When a row shows `sv` in the thousands, `position` around 70, hundreds of impressions and almost
+no clicks, and `serp` on that keyword says `listicle_window` — that is a complete, actionable
 picture: **the demand exists, the position is authority-limited, and the way in is the roundups,
-not another page.** This exact configuration is what clize.ai looked like on 2026-08-30.
-
-The mirror image is a word sitting in `unseen` round after round: no impressions at all means
-Google is not even offering you the surface. That is a **discovery** question (is this word
-reachable at your authority? what occupies it? — `seo serp`), not a measurement one. Running
-the measurement again will not answer it.
+not another page.** `check` now labels the middle of that sentence for you (`authority_limited`);
+the roundups still come from a deliberate `seo serp`.
 
 ---
 
-## 6. Two playbooks
+## 9. Two playbooks
 
-**New site, cold start.** `seo keywords` on your seed set → drop `wall`, keep `attackable` and
-interesting `no_volume` → `seo serp` each survivor → discard `official_wall` and
-`definition_wall` → for `listicle_window`, collect `parasiteTargets` and start outreach → write
-one page per surviving keyword following §4 → deploy → `seo check --keywords <the survivors>
---brand <you> --competitors <the two you keep seeing>`. That first check is your baseline.
+**New site, cold start.** `seo competitors <2–3 rivals>` → build the capability matrix (§1.2) →
+merge into 30–100 candidates → `seo keywords <the whole list>` in one call → drop `wall`, keep
+`attackable` and interesting `no_volume` → `seo serp` each survivor → discard `official_wall`
+and `definition_wall` → for `listicle_window`, collect `parasiteTargets` → write the table (§3)
+→ write one page per P0 row following §7 → deploy → `seo check --keywords <the survivors>
+--brand <you>`. That first check is your baseline. Total: about $1.
 
-**Recheck.** `clize seo check` with no flags (it remembers everything) → read `movers` first,
-then `traffic.ai`, then `gsc.newQueries`, then what is still in `unseen` → decide: keep waiting,
-add the new queries to the tracked list, or change approach. The check is free, so nothing stops
-you running it — but **SEO is a weeks-to-months system, and the window it measures is 4 weeks
-wide: checking daily just re-reads the same window.** Every two weeks is plenty.
+**Recheck.** `clize seo check` with no flags (it remembers everything) → read `signals` first,
+then `movers`, then `traffic.ai`, then `gsc.newQueries` → fold the new queries into the matrix
+and decide: keep waiting, extend the tracked list, or change approach. **SEO is a
+weeks-to-months system and the window it measures is 4 weeks wide: checking daily just re-reads
+the same window.** Every two weeks is plenty.
 
 ---
 
-## 7. Calibration discipline
+## 10. Calibration discipline
 
 Every measurement here is a sample, not a census. Rank sampling is one fetch of a personalized,
 rotating results page. Traffic is adaptively sampled. AI-engine visibility measured by any tool