@clize/clize 0.35.2 → 0.35.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clize/clize",
-  "version": "0.35.2",
+  "version": "0.35.4",
   "mcpName": "ai.clize/clize",
   "description": "The real-world capability layer for AI agents — domains, email, deploy, media, SEO/GEO. CLI + MCP.",
   "keywords": [

package/skills/clize-seo/SKILL.md

@@ -78,17 +78,32 @@ One free source comes before the paid ones: **the entry read's own gsc face** (
 `gsc.topQueries` / `newQueries` are Google's list of what it already considers you relevant for.
 On a site with history it is the best-fitted word source there is; on a new site it is empty.
 
-### 1.1 Competitor teardown — the only command that produces words
+### 1.1 The sweep — exhaust the competitor space once, then top it up
+
+`competitors` is the one command that hands you keywords you did not think of, and it is cheap
+enough to run to exhaustion — which no round had done before 2026-09-03: three sites, a dozen
+rivals torn down in total at `--limit 25`, ledgers of 40–60 rows on sites whose honest cell
+space is a few hundred. Do it once per site, and again whenever a product line is added:
 
 ```
-clize seo competitors rival-one.com rival-two.com --limit 25
+clize seo competitors a.com b.com c.com --limit 100        # one call per market: --locale
 ```
 
-Two or three competitors × `--limit 25` is 50–75 candidates for about $0.09 a domain, pre-filtered
-by the only filter that matters: somebody already ranks on them. Read `topKeywords[].keyword`,
-drop their brand terms, keep the rest. Pick rivals *your size or one step up* — a category
-leader's list is head terms you cannot have; the site ranking #4 on your queries hands you the
-reachable tail. Run this **first**, before writing down a keyword of your own.
+| step | size | cost |
+| --- | --- | --- |
+| list every rival: every host on every SERP you have bought (`items[].host`) plus each product line's direct rivals — sites your size or one step up, not category leaders (their list is head terms you cannot have) | 15–25 domains | $0 |
+| `competitors --limit 100`, per relevant market | 1,500–2,500 keywords, ~800 after dedupe | ~$0.04 a domain |
+| `seo keywords` on all of them, one call per market | ~800 | ~$0.20 |
+| `seo serp` on every `attackable`, `no_volume` and `no_data` survivor (§5) | ~300 | ~$6 |
+| rows into the ledger, each with a verdict | 80–120 buildable | — |
+
+About $8 and one session, and the ledger goes from forty rows to a hundred-plus. Read
+`topKeywords[].keyword`, drop their brand terms, keep the rest. Two things the sweep is not: it
+is not re-run every round (the 30-day cache makes that free and pointless — top up with the new
+hosts each round's SERPs reveal), and it does not replace §1.2 (a rival's list is what *they*
+rank for; your capability cells are what *you* can serve). Expect the SERP step to kill a third
+to a half of the low-KD survivors — walls the difficulty score cannot see (§4): PDF→Excel at KD 0
+in five markets was Adobe and iLovePDF in all five. That is the funnel working, not failing.
 
 ### 1.2 Capability-surface enumeration — cross the axes, don't brainstorm
 
@@ -126,7 +141,7 @@ A round is a funnel with a known size and a known price — and there is no such
 "analysis round": every round ends in pages or in a blocker the human must clear (§10).
 
 ```
-30–100 candidates            (§1: competitor teardown + capability matrix)
+500–1,000 candidates once   (§1.1 sweep), then 30–100 a round (§1.2 matrix + top-ups)
    → seo keywords            price the whole list in one batched call
    → drop `wall`; keep `attackable`, `no_volume` and `no_data`   (§5: the SERP decides, not the volume table)
    → seo serp each survivor  the SERP check that KD cannot replace  (§4)
@@ -140,12 +155,13 @@ A round is a funnel with a known size and a known price — and there is no such
 | 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 competitors`, one domain × `--limit 100` | **~$0.04** | the cheapest words you will ever buy — a 20-domain sweep is under a dollar |
 | `seo serp`, one keyword | **~$0.02** | every survivor gets one, `no_data` cells included — 20–100 of these is $0.40–2.00 |
 | `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 |
 | `seo spend` | **free** | itemized ledger of every charge — **copy it into the deliverable, never hand-tally** |
 
-**A complete cold start runs about $0.70–1.00.** That number is the *cost prior* — carry it.
+**The sweep is about $8, once; a round after it is about $1.** Those are the *cost priors* —
+carry them.
 
 Three behaviours follow, and all matter:
 
@@ -199,10 +215,10 @@ find out where every bet stands. `check` remembers the keyword list, the brand a
 property; it does not remember whether you shipped the page or sent the pitch, and it never
 will — it cannot measure those. That half of the state exists only here.
 
-| keyword | locale | sv | kd | serp verdict | intent | target page | page | placement | format | priority |
+| keyword | locale | sv | kd | serp verdict | intent | target page | page | placement | format · angle | priority |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| openrouter alternative | en-US | 1,300 | 1 | listicle_window | commercial | /compare/openrouter/ | shipped:/compare/openrouter/, 08-30 | pitched: apidog roundup, 08-31 | comparison + pitch 8 roundups | P0 |
-| email api for ai agents | en-US | 0 (no_volume) | — | listicle_window | commercial | /inbox/ | shipped:/inbox/, 08-27 | none | landing + pitch 4 roundups | P0 |
+| openrouter alternative | en-US | 1,300 | 1 | listicle_window | commercial | /compare/openrouter/ | shipped:/compare/openrouter/, 08-30 | pitched: apidog roundup, 08-31 | comparison · *the only gateway that publishes its failover log* + pitch 8 roundups | P0 |
+| email api for ai agents | en-US | 0 (no_volume) | — | listicle_window | commercial | /inbox/ | shipped:/inbox/, 08-27 | none | landing · *an inbox the agent owns, not a Gmail it borrows* + pitch 4 roundups | P0 |
 | メッセージストリームでエラー | ja-JP | 2,900 | 0 | definition_wall (UGC) | informational | — | none | none | skip: Reddit/Zenn own it | — |
 
 - **`target page` is the intent; `page` and `placement` are the facts.** `target page` says which
@@ -216,8 +232,10 @@ will — it cannot measure those. That half of the state exists only here.
 - **A row with a page and no placement is half a bet.** Building the page and not placing it is
   manufacturing stock and never shipping it — the failure shape in the formula up top. The
   `placement` column is there so that half is visible at a glance instead of buried in prose.
-- **`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.
+- **`target page`, `format` and the angle 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 — and the angle (§7.1 ①) is the one line that says why that page and not a
+  competent copy of the occupants.
 - **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.
 - **Opening the ledger on a site that already has analysis documents** (a plan, an older
@@ -239,11 +257,13 @@ will — it cannot measure those. That half of the state exists only here.
 - **Every ledger file counts, and a plan is a queue.** A site may carry more than one ledger
   (tabledi: `worksheet.md` for en-US and `worksheet-global.md` for the other markets); rows in
   all of them are the site's rows, and a round that counts only one file will report "nothing
-  to build" beside 27 verified cells. A batch plan written under an earlier count rule (`≤5,
+  to build" beside the cells the other file already verified. A batch plan written under an earlier count rule (`≤5,
   wait for impressions`) is not re-planned and never "the next batch": each cell is re-gated
   on its own SERP verdict, and every cell that passes is a `to build` row for step ⓪ of the
-  next session (§10). tabledi's B1–B4 — 27 locale tool cells, 15 SERPs bought — sat under
-  "next batch" through three sessions.
+  next session (§10). tabledi's B1–B4 sat under "next batch" through three sessions — and when a
+  session finally counted, only 15 of its cells had a SERP and 6 of those were unbuilt: a plan
+  is not a verified list until each cell has its own verdict; buy the missing ones ($0.02 each)
+  in the same session, never "next time".
 
 **Page batches — the second table in the ledger.** Keyword rows hold bets; the batch table holds
 what the site's composition is doing, and it is what the batch gate and the retire rule (§7.3)
@@ -295,8 +315,13 @@ run* — all six have been observed in real runs that read as finished.
    An opportunity written in prose (a cluster, a family, a locale axis) with no rows behind it
    is test 1 wearing a different coat. The deliverable counts shipped
    URLs, not qualified rows; a ledger of twenty rows and two pages is a session that spent itself
-   on the analysis. Observed on our own tenant zero: eleven weeks of rounds that produced ledgers
-   and no pages. If a page costs a session, the first deliverable is the generator (§7).
+   on the analysis. Observed on kunavo: five rounds, five pages, three of the rounds at zero; and on clize.ai
+   the opposite failure — eleven weeks in which no round ran at all. If a page costs a session, the first deliverable is the generator (§7).
+7. **Pages without a brief.** A page whose row names no occupant gap and no product asset is a
+   competent copy of the top 10, and at zero authority a competent copy does not rank: kunavo's
+   five model spec pages, built from the query alone against a page of opinion pieces, read zero
+   for three to eight weeks. The brief (§7.1 ①) is written before the page, and its angle sits in
+   the ledger row; no angle, no page.
 
 ---
 
@@ -415,10 +440,11 @@ So: a `no_volume` row whose SERP is already full of category roundups is worth a
 A `no_data` row goes to `seo serp` like any other survivor — the SERP does not need a volume
 figure to show who occupies it. Open and servable → buildable, enrolled as `pending`; wall →
 skip row with the reason. What `no_data` never is: a reason to drop the cell. Measured across
-three sites, the rows with the best positions were disproportionately ones the volume table
-could not see (kunavo's payment long-tails at 4.5 and 5.8, clize.ai's German MCP cluster at
-130 impressions), while the priced `attackable` rows sat at 65+ — the table's coverage and the
-incumbents' coverage are the same coverage. On 2026-09-02, 82 of 119 cells left the funnel at
+three sites: the demand the table could not see was real (clize.ai's German MCP cluster,
+`no_data` in the table, 130 impressions in Search Console), and the only page-1 positions any
+of the sites hold are on such cells (kunavo's payment long-tails at 4.5 and 5.8), while the
+priced `attackable` rows sat at 65+ or unseen — the table's coverage and the incumbents'
+coverage are the same coverage. On 2026-09-02, 82 of 119 cells left the funnel at
 the pricing step without a single SERP look; keeping them would have cost $1.64 in serp calls.
 
 ### `--ai` is a different unit
@@ -547,22 +573,33 @@ a family generator existed, and tabledi shipped forty in two days from one. Buil
 before the second page of any family, and never machine-translate a family page.
 
 **On a site that already has tools, this round's page count is the locale siblings of the tools
-it has.** A sibling is one strings entry (tabledi: a `DICT` table in `tools/apps.js`; clize.ai:
-a `strings.<loc>.mjs`) and its gate is its own SERP (§7.2). Count existing tools × verified
-locale cells before anything else — tabledi had 23 tools, 6 markets, 27 cells already verified
-open, and three sessions wrote "next batch" beside them while building one page. New tools are
-code and tests, one to three per session: they are the next batch's rows, not this batch's
-excuse. And **building a page that passed the gates is never a question for the human.** The
-human's gates are money, external-facing changes (a redirect, DNS, a published post) and sends.
-Ask for those in one line and build while you wait — never bundle the pages into the question
-(tabledi, 2026-09-02: one redirect that needed a yes was asked together with three pages that
-did not, and all four waited).
+it has**, and the gate is each cell's own SERP (§7.2). Siblings come in two prices. A *format*
+tool (viewer, merge, split, convert) is one strings entry (tabledi: a `DICT` table in
+`tools/apps.js`; clize.ai: a `strings.<loc>.mjs`) — ten in a session is ordinary. A *text* tool
+(duplicates, compare, clean) carries locale semantics — full-width and half-width forms in
+Japanese, composed and decomposed accents in French — and a sibling that ignores them reports
+"0 duplicates" on a real file, which is gate 3 failed; budget two or three of those per session.
+Count existing tools × verified locale cells before anything else, and buy the SERPs the cells
+lack ($0.02 each) in the same breath — tabledi had 23 tools and 6 markets; when a session
+finally counted, 15 cells had a SERP, 6 were passed and unbuilt, and "next batch" had been
+written beside them three times. New tools are code and tests, one to three per session: the
+next batch's rows, not this batch's excuse.
+
+**Building and publishing a page that passed the gates on the user's own site is never a
+question for the human.** The human's gates are money, changes that alter what the world already
+sees (a redirect, DNS, a canonical), sends, and posts on other people's platforms. Ask for those
+in one line and build while you wait — never bundle the pages into the question. When a
+human-gated change shares a deploy with pages (a redirect map in the same `vercel.json`), split
+the deploy: ship the pages, hold the change. Step ⓪ is done when the pages are *live*, not
+committed — tabledi, 2026-09-02: one session built three things and ended asking about a
+redirect; the next found all three returning 404 in production and ended the same way. Four
+pages built across two sessions, zero live. A session does not end with built, undeployed pages.
 
 ### 7.1 The pipeline — five steps, each with a pass/fail
 
 | step | act | it passed if |
 | --- | --- | --- |
-| ① outline | derive structure from `serp`'s `items` (data you already paid for): page type from what the top 10 is, length ≈ closest-shaped rival × 1.1–1.2, topic list from what they cover plus the gap you fill | every H2 can name which SERP occupant or gap it answers; delete any H2 that can't |
+| ① brief | five fields, written into the row before a word of the page: **intent** — what the searcher wants, from the query, the shapes in the top 10, and Search Console when the site already earns on it (§4); **occupants** — open and *read* the top 3–5 pages, not their titles: structure, length, what each answers, promises and lacks (you fetch them yourself; there is no command for this and $0); **product truth** — what the product actually does for this intent (gate 3) and what only it has: first-party data, a working tool, a capability the occupants lack; **angle** — one sentence naming an occupant gap that a product truth fills; **form** — page type from what the top 10 is, length ≈ closest-shaped rival × 1.1–1.2, every H2 mapped to an occupant or a gap, the first 200 words, the FAQ in that market's phrasing. One brief per family; locale siblings change terminology and FAQ only | the angle names a gap *and* an asset — no angle, no page, and the row becomes `skip: no angle`. The three pages that worked had one (clize's OpenClaw page: "an inbox the agent owns" against two "borrow your Gmail" occupants; tabledi's Japanese dedupe: full-width forms, which a wall of tutorials never mentions; kunavo's 529 page: real failover numbers nobody on the page had); the five that read zero did not |
 | ② produce | skeleton from `build site start`, judgment from here, words and code from you | first 200 words answer the query completely; your definition sentence is verbatim-identical site-wide |
 | ③ self-check | against the spec sheet — there is deliberately no audit command | visible FAQ ↔ JSON-LD strictly 1:1; ≥2 internal links with varied anchors |
 | ④ deploy | ship it | page live, in sitemap |
@@ -586,11 +623,17 @@ Judgment calls that matter:
   translates almost for free, and the non-English cells of your matrix are the low-competition
   ones. Each locale page is a real, distinct intent — this is not page-stuffing. Build every
   locale cell whose *own* SERP is not a wall (`seo serp --locale`, $0.02); the English page's
-  impressions are not the gate, because locale SERPs are only loosely coupled — a browser CSV
-  tool holds #1 in German where the English SERP is a tutorial wall, and a Korean payment
-  long-tail ranked where its English sibling never did. What does not multiply: marketing and
-  landing pages. Locale copies of those earned zero on every site measured (72 on clize.ai, 199
-  near-identical on kunavo) and are the composition drag gate 4 exists to prevent.
+  impressions are not the gate, because the same intent draws a different page in each market —
+  kunavo's `claude code pricing`: `official_wall` in de-DE and es-ES, `open` in ja-JP and
+  fr-FR; one keyword, four verdicts. What does not multiply: marketing and landing pages. Read
+  that evidence for what it varied, not for what it sounds like: clize.ai's 72 translated
+  landing pages earn about what their English originals earn — impressions in the tens, zero
+  clicks — so the failure is the *type*, in every language; kunavo's 199 untranslated copies
+  were duplicates, collapsed by canonicalization, and say nothing about locales; the locale
+  pages that do earn on both sites are translated guides and tools (kunavo's Korean pricing
+  guide is its top non-brand page). The bar for adding a locale to a marketing page is local
+  non-brand impressions on the ones that exist — indexing is the floor, not the pass. Locale is
+  not a page-generation primitive; a SERP-backed intent is.
 - **Pick tools with a shelf life.** Protocol- and format-level tools (llms.txt, schema, robots)
   keep earning links for years; trend-chasing tools die with the trend. Ask: will anyone search
   this in a year?
@@ -622,16 +665,23 @@ do the protecting, not experience:
      locale page written in-locale, a host page whose install and config really differ;
    - **the last batch is being indexed** — `gsc.pages.unseen` (§9) shows the previous batch's
      `index`; find the batch by `firstSeen`, and book the counts in the ledger's batch table (§3).
-     Mostly `indexed` → ship the next family. Mostly `Crawled - currently not indexed`
-     → that is Google's own verdict on those pages; the round is indexing and pruning, not
-     shipping.
+     Read the four states apart: `URL is unknown to Google` and `Discovered - currently not
+     indexed` are the queue (a day-old batch sits there; not a verdict); `Crawled - currently
+     not indexed` is Google's verdict on a page it has read — after you rule out your own hand
+     (a canonical pointing elsewhere, hreflang missing or one-way, a stray `noindex`), which
+     produces the same state. Mostly indexed → ship the next family. Mostly crawled-not-indexed
+     on a clean implementation → the round is indexing and pruning, not shipping. This check
+     paces shipping; it does not certify composition — kunavo's 440 locale model pages indexed
+     fine and earned nothing. Composition is the second check and the retire rule.
    Impressions are not the gate for the next batch: at zero authority they arrive five to six
    weeks after shipping and clicks may not arrive in a quarter, so a rule that waits for them
    ships nothing for months — that was the mechanism behind five pages a month. Waiting is for
    *deciding a new page type* (§10), never for the siblings of a type already decided. The
    retire rule is the other half of shipping fast: a page indexed for two windows with no
-   impressions, or refused by the index for two, is noindexed, merged or redirected. The
-   composition stays clean only if dead pages leave.
+   impressions, or refused by the index for two, is retired: `noindex` by default (the page keeps
+   serving users, only its index exposure goes), merge or redirect when another page carries the
+   intent, delete only what nobody visits. The composition stays clean only if dead pages leave
+   the index.
 
 ### 7.4 E-E-A-T floor and locales
 
@@ -669,17 +719,13 @@ the 3–5 questions your money pages answer in the engines themselves (~15 minut
 and note who gets named. Zero is a reading.
 
 **Do not build a citation-probe cron** — a saved prompt set fired at N engines on a schedule.
-Field-tested and rejected, for three reasons that don't age: self-authored prompts carry
-self-confirmation bias (hits on questions you wrote prove little about questions users ask); on
-a low-authority site the output is a flat zero line that still costs keys, spend caps and
-upkeep; and a scheduled measurement nobody is present to act on is inventory, not signal — one
-such cron sat dark for two weeks without a single decision changing, which is the whole case in
-one sentence. A probe earns its keep only once there is something to *attribute*: sustained AI
-referrals (tens per month, holding for two months), a real attribution question ("why does the
-engine name the competitor and not us?"), or a before/after comparison around a content-pack
-launch. Until one of those fires, referrers plus the spot-check are the honest instruments.
-And all AI-citation measurement is sampling — trust trends against your own baseline, never
-absolute share.
+Field-tested and rejected: self-authored prompts carry self-confirmation bias, a low-authority
+site's probe is a flat zero line that still costs keys and upkeep, and a measurement nobody is
+present to act on is inventory (one such cron sat dark for two weeks without a decision
+changing). A probe earns its keep only when there is something to *attribute* — sustained AI
+referrals, a real attribution question, a before/after around a launch. Until then, referrers
+plus the spot-check; and all AI-citation measurement is sampling — trends against your own
+baseline, never absolute share.
 
 ---
 
@@ -814,7 +860,8 @@ appeared, stop where none did, and keep enumerating cells the ledger has not pri
 
 **A round is a pipeline, and it opens by building.** ⓪ **ship the qualified batch** — every
 `to build` row from the last round and every plan cell with its own SERP verdict (§3), in every
-ledger file — before reading a single number, while the session's budget is whole → ① read the
+ledger file, each built from its brief (§7.1 ①) — before reading a single number, while the
+session's budget is whole → ① read the
 feedback (`check`, free) → ② allocate (double down / stop loss / new bet) → ③ execute what is
 cheap now (siblings, retargets, placement drafts) and write the rest as the next session's
 `to build` rows → ④ book it (§3) → ⑤ report it (two tables, below). This round's analysis
@@ -881,18 +928,19 @@ to fill in. That state lives in the ledger or nowhere.
 What the human reads ends with two tables, not with findings. First, **this round's pages** —
 every row the round touched, one line each:
 
-| keyword | locale | serp | target URL | type | status |
-| --- | --- | --- | --- | --- | --- |
-| hreflang 生成 | ja-JP | open (small sites) | /ja/seo/hreflang-tag-generator/ | tool | built |
-| open webui api key | en-US | open | /docs/integrations/open-webui | integration doc | to build: generator first |
-| claude code preise | de-DE | official_wall | — | — | skip |
+| keyword | locale | serp | target URL | type | angle | status |
+| --- | --- | --- | --- | --- | --- | --- |
+| hreflang 生成 | ja-JP | open (small sites) | /ja/seo/hreflang-tag-generator/ | tool | also emits the sitemap `xhtml:link` block — no occupant does | built |
+| open webui api key | en-US | open | /docs/integrations/open-webui | integration doc | the one setup page that states the model-routing limit | to build: generator first |
+| claude code preise | de-DE | official_wall | — | — | — | skip |
 
 `status` is one of `built` (shipped this round), `to build`, `exists` (a page already carries
 it), `skip` (with the reason). A `to build` row carries a blocker, and only three exist:
 `needs human` (a redirect, a send, money — asked in one line, §7), `needs tool code` (a new
 client-side tool; name the session it ships in), `needs generator` (no family scaffold yet).
-"Analysis round", "next batch" and "awaiting go-ahead" are not blockers — a row wearing one of
-those means the session is not finished, and it goes back to step ⓪. Second, **placement** — target /
+"Analysis round", "next batch", "awaiting go-ahead" and "needs a SERP" are not blockers — a
+SERP is $0.02 inside the fuse and is bought on the spot — and a row wearing one of those means
+the session is not finished: it goes back to step ⓪. Second, **placement** — target /
 page / status (`sent` / `drafted` / `blocked: needs human`). Then at most five lines of
 narrative. A report that is findings and no pages table is test 1 (§3) in its final form: the
 human cannot act on a paragraph. A round with an empty pages table says so *in* the table, with
@@ -925,6 +973,14 @@ So: **promise time series against yourself, never absolute share.** "Our AI refe
 it. Breaking this rule in customer-facing copy is a product-integrity failure, not a rounding
 error.
 
+**The cases in this file are samples of one to three sites, and each varied one thing.** Before
+a case is cited for a rule, say what it varied, how many, and over which window: clize.ai's 72
+locale pages varied *page type* (their English originals earn the same nothing); kunavo's 199
+copies varied *translation* (identical, so Google collapsed them); tabledi's page-1 tools varied
+*age* (three years), not links; tabledi's 36 marketing locales were a day old when first read.
+A rule that survives only because its example was misread is a rule waiting to fail — three
+such misreadings were found in this file on 2026-09-02 and corrected.
+
 ---
 
 ## What this skill will not do