seo 0.2.20 → 0.2.22

package/README.md

@@ -70,7 +70,8 @@ through adding your own desktop OAuth client.
 
 Research providers are optional and connected separately. Start with the main
 report, then add DataForSEO when keyword estimates, live results, domain
-footprints, ranking pages, or competitor research would change the decision.
+footprints, ranking pages, competitor research, or exact local result context
+would change the decision.
 
 That is the normal path. The `seo` command is then available in every terminal,
 script, CI job, and local MCP client on the machine.
@@ -133,6 +134,8 @@ Use `seo help all` for the longer command list.
   ranks.
 - Detect repeated first-party and competitor page patterns, then return bounded
   data-source research briefs before proposing a new programmatic template.
+- Find location-specific Search Console demand and repeated local page patterns,
+  then add a few exact local result snapshots when the decision needs them.
 - Give scripts and agents deterministic JSON, Markdown, stable rule IDs, and a
   compact local MCP surface.
 
@@ -209,6 +212,7 @@ commands:
 seo reports describe keyword-research --json
 seo reports describe domain-overview --json
 seo reports describe competitor-keyword-gap --json
+seo reports describe local-search-demand --json
 
 seo reports run domain-overview \
   --params '{"domain":"example.com","countryCode":"GB","languageCode":"en"}' \
@@ -228,13 +232,21 @@ The research flow now covers:
   community, or marketplace;
 - `competitor-keyword-gap` for comparing up to three relevant domains with
   retained Search Console themes, the site's provider-observed rankings, and
-  programmatic page patterns.
+  programmatic page patterns;
+- `local-search-demand` for matching explicit place names, nearby phrases, and
+  postal codes in retained Search Console rows, reviewing repeated local page
+  patterns, and optionally adding up to three exact local result snapshots;
+- `link-evidence` for a current link summary, one representative backlink per
+  referring domain, and linked-target checks against saved crawl and Search
+  Console evidence.
 
 Provider traffic, volume, difficulty, intent, visibility, and ranking history
 are estimates. Search Console remains the evidence for measured search
 performance on a property you own. A live result snapshot remains the evidence
 for one query, market, device, and observation time. Reports can combine these
 sources without blending their meanings or turning a missing row into zero.
+Local query wording does not establish the searcher's physical location, and an
+observed local pack does not establish that a particular listing appeared.
 
 Read the [research provider guide](https://seoskill.dev/docs/research-providers)
 for setup, costs, caching, country-level limits, competitor classification, and
@@ -269,18 +281,35 @@ evidence remain distinct. Bing's `inIndex` crawl statistic is provider
 evidence, not URL-level proof that a page is indexed. A query or page missing
 from a weekly top list is unknown, not zero.
 
-Use the same connection to review a bounded set of referring links, or import
-an export from another source:
+Review a bounded set of referring links from DataForSEO, Bing or a local
+export:
 
 ```sh
+seo links --provider dataforseo --target example.com --json
+seo links --provider dataforseo --target example.com \
+  --search-site sc-domain:example.com --json
 seo links --project example --json
 seo links --file ./links.csv --row-limit 10000 --json
 ```
 
+The DataForSEO path makes two sequential paid requests by default: one summary
+and up to 100 live representative backlinks, one per referring domain. Current
+endpoint prices, estimated and actual cost, task ids, cache state, provider
+filters, row coverage and omitted rows stay in the result. A cached repeat
+does not repeat paid work during the retention window.
+
+When a matching saved crawl or Search Console property is available, the same
+report checks linked target pages for observed error responses, redirects,
+canonical conflicts and non-indexable states. Search Console metrics add
+first-party context without turning a missing retained page row into zero.
+Verify the live target and the referring page before changing anything.
+
 CSV and JSONL imports stream from disk. Regular JSON arrays have a smaller
 file limit to avoid a memory spike. Every result includes the number of rows
 read, rejected, deduplicated, omitted, or stopped by a limit. It is evidence
-from the selected source, not a complete backlink index or an authority score.
+from the selected source, not a complete backlink index. Provider rank and
+spam metrics keep their provider-specific names and scales. They are context,
+not search-engine ranking factors or universal authority scores.
 
 ## Create an HTML report for a client