seo-intake · git:20260821.6980081 · 2026-08-21 · sha256 0c2c905888832721
seo-intake git:20260821.6980081A
Immutable. This exact content is served forever at /api/v1/blob/0c2c905888832721.
--- name: seo-intake description: Run and read the SEO intake pipeline. Pulls the organic keyword set for your domain and for each competitor through the Monid tool layer, computes the gap locally, and routes every keyword to the one action that can help it (write-new / striking / build-depth / defend / noise). Use when asked to refresh the SEO queue, decide what content to commission, check keyword gaps or rankings, or read the intake. Triggers "SEO queue", "keyword gap", "what should we write", "seo intake", "rankings", "competitor keywords". --- # SEO intake Project: your clone of `agent-seo-kit`. Every network call goes through Monid, so there is one key, one balance, and one place the cost is visible. Two halves feed one queue: - **Where you stand**: the keywords your domain already ranks for, and at what position. - **Where the gap is**: the keywords your competitors earn traffic from and you do not appear for at all, computed as a local set difference. The queue is the product. Everything else exists to make it trustworthy. ## The rule the whole thing rests on **Every topic must trace to evidence of real demand.** A keyword tool, a real thread, first party research. Never a model's suggestion. The moment a topic is invented, every number downstream becomes decoration and the pipeline is manufacturing pages nobody wants. When asked to add a topic with no keyword behind it, say so and offer to check its volume first rather than adding it. ## Setup, once This kit has no API keys of its own. It borrows Monid's, which is the point: Semrush, Ahrefs, Reddit and the answer engine all arrive through one account instead of four contracts. 1. Install the `monid` skill and its CLI, then add a key: ```bash npm install -g @monid-ai/cli@latest monid setup monid keys add -k <key from https://app.monid.ai/access/api-keys> -l main ``` 2. Copy the config and fill it in: ```bash cp seo.config.example.json seo.config.json ``` `site.domain`, `site.brandTerms` and `competitors` are the three fields that decide whether the output is useful. Get the competitors right by hand: see the traps below. 3. Check the paid reports are enabled on the workspace. Ahrefs and Semrush are entitlements, not public endpoints, so a fresh workspace can see them in `monid discover` and still be refused at run time. If a pull fails with a permission error, the README says who to ask; it is free to enable. ## Commands ```bash node scripts/pull-organic.mjs --dry-run # quote the cost, spend nothing node scripts/pull-organic.mjs # your domain + every competitor node scripts/pull-organic.mjs --only competitor-a.com --limit 100 node scripts/classify.mjs # free: routes what was already bought ``` **Always run the dry quote first when the row cap moves.** These reports bill per returned row, and `limits.rowsPerDomain` is the cost dial and nothing else. The difference between the two sources is not small: | source | per row | max per call | when | |---|---|---|---| | `ahrefs` | about 36x the Semrush rate | 100 | the default. Also the only one that can measure AI citations. | | `semrush` | the cheap one | 10,000 | when you want depth and the row budget is what is stopping you. | Switching is one field in the config. Nothing downstream knows which one ran. ## The five buckets, and why confusing two of them wastes money | Bucket | Symptom | Action | |---|---|---| | `write-new` | No page of yours competes; a competitor ranks | Commission content | | `striking` | You rank 4 to 20, one push from the first page | Rewrite the title, add depth, earn a link | | `build-depth` | You rank 21 to 60, barely shown | Internal links, depth, references | | `defend` | You rank 1 to 3 | Leave it alone unless it slips | | `noise` | Brand, typo, under the volume floor, or out of reach | Ignore, deliberately | **A title rewrite only helps a page that is already being shown.** Spend one on a `build-depth` keyword and nothing happens, because almost nobody is seeing the result to not click it. This is the most common wasted action in SEO and the main reason the classifier exists. The bands are in `seo.config.json` and they are **starting assumptions, not measured truth**. Say so whenever you report a number that depends on one. ## Reading the data without fooling yourself 1. **Is the keyword above the noise floor?** One or two searches a month is a long tail accident, not a trend, and rate maths on tiny denominators is theatre. `limits.minVolume` exists for this. 2. **Is a brand term doing the work?** A young domain's organic footprint is mostly its own name. Left in, brand terms dominate every average and the pipeline writes articles for people who already found you. `brandTerms` catches the obvious ones and near typos; check the `noise` bucket by eye after the first run and add what leaked. 3. **How many competitors rank for it?** One competitor at position 9 is weak evidence. Three of them ranking is the category telling you the question is real. `confirmedBy` carries that count. 4. **Was the row cap the limiting factor?** Every count in `intake.json` is bounded by `rowsPerDomain`. `coverage` records it. Reporting the gap without saying what bounded it overstates coverage, every time. ## Known traps, all of them observed in real runs - **Pull competitor keywords by traffic, not by volume.** Volume sorted returns the mega terms at the top of the category that nobody in a normal competitive position could rank for. Traffic sorted returns what is really sending them visitors. The adapter already sorts this way; do not "fix" it. - **Scraping and tooling competitors drag adult and piracy traffic into the gap.** This is not hypothetical: a three domain test run put "xhamster downloader" and "erome downloader" in the top ten write-new rows, both real keywords a competitor really ranks for, and both worthless. Keep `excludeKeywordPatterns` populated and **eyeball the queue after any competitor change**. It is a blocklist, so it only catches what it knows. - **Automatic competitor discovery does not work for a young domain.** The comparison data is not there, and what comes back is a directory site and a social network at near zero relevance. Hand pick the competitor list and keep it hand picked until the domain has a real footprint. - **A competitor's own brand terms are their navigation, not your opportunity.** The classifier drops them. If a competitor's product name is also a common word, the drop is too aggressive, and that is worth knowing before you conclude they rank for nothing. - **A domain property covers subdomains.** Docs, app and marketing pages can all appear. Read the ranking URL, not just the position, before deciding which page moved. - **The Monid CLI cannot be driven through a shell on Windows.** The `.cmd` shim mangles JSON arguments and rewrites POSIX looking endpoint paths into drive letters. `lib/monid.mjs` resolves the package entry and runs it under `node` directly. Do not "simplify" that back to a shell call. - **Fire and poll, never wait inline.** When an inline wait window closes on a run that is merely slow, the CLI exits non zero and the run id goes with it, so a job that was about to finish looks exactly like one that failed. ## When reporting results - Name the source (`ahrefs` or `semrush`), the country, and the row cap. - Separate measured from assumed. The bands are assumed until recalibrated. - Give the cost of the pull. - Do not present a `write-new` row as a brief. It still needs a human check on whether you can honestly serve that topic, and on which page it should send a reader to. ## What comes next `classify.mjs` writes `data/intake.json`. On its own that is half a picture: it says what search demand looks like and nothing about whether an AI answer names you. Run `geo-monitor` for the other half, then `node scripts/build-content-library.mjs` to fuse them. A topic confirmed on both surfaces is the strongest target this pipeline can produce.