feat(ahrefs): add provider adapters

PRIVACY.md

@@ -1,6 +1,6 @@
 # Privacy policy
 
-Last updated: 23 July 2026
+Last updated: 24 July 2026
 
 This policy covers the official `seo` command-line tool, library, MCP server,
 and the seoskill.dev website.
@@ -106,31 +106,32 @@ it before trying again.
 
 ## Optional research provider requests
 
-DataForSEO requests can send the exact inputs needed for the selected
-operation. Depending on the report, these can include:
+Research-provider requests send only the inputs needed for the selected
+operation. Depending on the provider and report, these can include:
 
 - keywords, research seeds, domains, URLs, filters, result limits, country,
   language, location, and device;
 - target names and aliases used for indexed AI mention research; and
 - the full fixed prompt, selected model, country, web search setting, and
   output limit used for an AI prompt observation.
 
-Your DataForSEO login and API password authenticate these HTTPS requests. The
-project maintainer does not receive the credentials, inputs, or responses.
-DataForSEO processes them under its
+DataForSEO requests use your login and API password. Semrush requests use your
+Version 3 API key and can include the regional database, selected columns, and
+report limits. Ahrefs requests use your API v3 bearer key and can include the
+target mode and country filter. Each provider also receives ordinary network
+metadata.
+
+The project maintainer does not receive these credentials, inputs, or
+responses. DataForSEO processes them under its
 [privacy policy](https://dataforseo.com/privacy-policy). As of the date of this
 policy, DataForSEO says it stores API task data for 365 days. Its policy and
-retention can change independently of this project.
-
-The exported TypeScript library also includes a Semrush adapter. If you
-configure and call it, Semrush receives the API key and the phrase, domain,
-URL, database, columns, and limits needed for that request. The current CLI
-uses Semrush and Ahrefs ranked-keyword exports as local files rather than live
-connections. Importing a provider file does not upload it to the provider or
-the project maintainer. The Semrush library adapter caches responses locally
-for up to 14 days. Cache maintenance enforces a 16 MiB Semrush-cache limit and
-removes rows older than 30 days. Run
-`seo cache clear --provider semrush` to remove those cached responses.
+retention can change independently of this project. Semrush and Ahrefs process
+requests under their respective
+[Semrush privacy policy](https://www.semrush.com/company/legal/privacy-policy/)
+and [Ahrefs privacy policy](https://ahrefs.com/legal/privacy-policy).
+
+Importing a local DataForSEO, Semrush, or Ahrefs file does not upload it to the
+provider or the project maintainer.
 
 ## Bing Webmaster requests
 
@@ -172,23 +173,27 @@ That transfer is controlled by the client and model service, not by the local
 ## How long research data is kept locally
 
 DataForSEO responses are cached locally for up to 24 hours or seven days,
-depending on the operation. Cache maintenance removes provider cache entries
-older than 30 days and enforces a 32 MiB provider-cache limit. On a machine
-where the command is no longer run, expired rows can remain until you clear the
-cache or reset the software.
+depending on the operation. Semrush responses are cached for up to seven days.
+Ahrefs Domain Rating responses are cached for up to 24 hours, and other Ahrefs
+responses are cached for up to seven days. Cache maintenance removes provider
+cache entries older than 30 days and enforces a 32 MiB provider-cache limit.
+On a machine where the command is no longer run, expired rows can remain until
+you clear the cache or reset the software.
 
 Fixed AI prompt observations are saved locally so repeated runs can show
 compatible changes over time. History is bounded to 90 observations for one
 exact configuration, 10,000 observations in total, and 128 MiB of logical
 storage. The local provider spend ledger is retained for up to 730 days and is
 bounded to 50,000 rows and 32 MiB.
 
-Run `seo cache clear --provider dataforseo` to remove cached DataForSEO
-responses. Run `seo providers dataforseo disconnect` to remove saved
-credentials. These commands do not delete task data already processed by
-DataForSEO. Run `seo reset --yes` to remove every saved provider credential
-along with local configuration, caches, histories, spend records, logs, and
-saved reports.
+Run `seo cache clear --provider dataforseo`,
+`seo cache clear --provider semrush`, or
+`seo cache clear --provider ahrefs` to remove one provider's cached responses.
+Run the matching `seo providers <provider> disconnect` command to remove its
+saved credential. These commands do not delete data already processed by an
+external provider. Run `seo reset --yes` to remove every saved provider
+credential along with local configuration, caches, histories, spend records,
+logs, and saved reports.
 
 ## Anonymous tool usage
 
@@ -253,14 +258,15 @@ copy, publish, transmit, or pass it to an agent or application yourself.
 
 ## Removing access and local data
 
-Use `seo auth logout` to remove local Google tokens,
-`seo providers dataforseo disconnect` to remove saved DataForSEO credentials,
-`seo providers bing disconnect` to remove the saved Bing credential, and
-`seo indexnow remove --site https://example.com` to remove a saved IndexNow key
-for one site. Environment variables are controlled by your shell or runtime and
-are not changed by these commands. Use `seo privacy` to inspect local paths and
-`seo reset --yes` to remove every saved credential and local file managed by
-the software.
+Use `seo auth logout` to remove local Google tokens. Use
+`seo providers dataforseo disconnect`,
+`seo providers semrush disconnect`, `seo providers ahrefs disconnect`, or
+`seo providers bing disconnect` to remove the corresponding saved provider
+credential. Use `seo indexnow remove --site https://example.com` to remove a
+saved IndexNow key for one site. Environment variables are controlled by your
+shell or runtime and are not changed by these commands. Use `seo privacy` to
+inspect local paths and `seo reset --yes` to remove every saved credential and
+local file managed by the software.
 
 You can also revoke the app from your
 [Google Account connections](https://myaccount.google.com/connections).

README.md

@@ -69,9 +69,8 @@ the shared Google app. If it is unavailable in your build, setup guides you
 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, competitor research, or exact local result context
-would change the decision.
+report, then add DataForSEO, Semrush, or Ahrefs only when external keyword,
+result, domain, competitor, or link estimates 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.
@@ -188,8 +187,9 @@ Run `seo help` for the short path or `seo help all` for the full command list.
 
 ## Research keywords and competitors
 
-Connect DataForSEO when you need independent market estimates or competitor
-evidence. The connection is local and separate from Google sign-in:
+Connect a research provider when you need independent market estimates or
+competitor evidence. Each connection is local and separate from Google
+sign-in. DataForSEO has the broadest live coverage:
 
 ```sh
 seo providers dataforseo connect
@@ -198,10 +198,23 @@ seo providers dataforseo limits
 ```
 
 Credentials use the system keychain when available, with a private local file
-fallback. Paid requests read current endpoint prices, reserve estimated spend
-before acquisition, record actual cost, and use local daily, monthly, request,
-and row limits. Cached results avoid repeating paid work during their retention
-window.
+fallback. Semrush Version 3 and Ahrefs API v3 use the same local credential
+boundary:
+
+```sh
+seo providers semrush connect
+seo providers semrush status --check
+
+seo providers ahrefs connect
+seo providers ahrefs status --check
+seo providers ahrefs limits
+```
+
+Read the [Semrush guide](https://seoskill.dev/docs/semrush) and
+[Ahrefs guide](https://seoskill.dev/docs/ahrefs) before running paid research.
+Supported reports record the applicable API units or USD cost, cache state,
+request bounds, and retained row coverage. Cached results avoid repeating paid
+work during their retention window.
 
 Use the existing report catalog. There are no separate provider-named report
 commands:
@@ -264,6 +277,8 @@ The research flow now covers:
 - `link-evidence` for a current link summary, one representative backlink per
   referring domain, and linked-target checks against saved crawl and Search
   Console evidence;
+- `domain-rating` for one free, attributed Ahrefs observation of backlink
+  profile strength, kept separate from ranking and traffic evidence;
 - `ai-mention-research` for provider-indexed mentions, cited domains, and
   bounded question samples in one exact AI surface and market, with optional
   Search Console overlap for a property you own;
@@ -319,22 +334,24 @@ 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.
 
-Review a bounded set of referring links from DataForSEO, Bing or a local
-export:
+Review a bounded set of referring links from Ahrefs, DataForSEO, Bing or a
+local export:
 
 ```sh
+seo links --provider ahrefs --target example.com --json
 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.
+The Ahrefs and DataForSEO paths request one summary and a bounded set of live
+representative backlinks, one per referring domain by default. Ahrefs keeps
+estimated and actual API units in the evidence. DataForSEO keeps current
+endpoint prices, estimated and actual USD cost, and task ids. Both retain cache
+state, provider filters, row coverage, and omitted rows. 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,
@@ -654,9 +671,9 @@ request a site, connected Google or Bing account, research provider, Chrome UX
 Report, IndexNow, or the npm registry when the work needs it.
 
 Optional external enrichment can send selected Search Console query or derived
-seed text to DataForSEO only when you explicitly enable it. It does not send
-Google credentials, property IDs, Search Console metrics, or Google Analytics
-rows. Local provider file imports are not uploaded. Read the
+seed text to the chosen research provider only when you explicitly enable it.
+It does not send Google credentials, property IDs, Search Console metrics, or
+Google Analytics rows. Local provider file imports are not uploaded. Read the
 [privacy policy](https://seoskill.dev/privacy) for every network boundary and
 the [telemetry page](https://seoskill.dev/telemetry) for the fixed anonymous
 usage-event schema and opt-out controls.

apps/web/public/sitemap.xml

@@ -37,6 +37,7 @@
   <url><loc>https://seoskill.dev/docs/reports/site-crawl</loc></url>
   <url><loc>https://seoskill.dev/docs/reports/ctr-underperformers</loc></url>
   <url><loc>https://seoskill.dev/docs/reports/decaying-pages</loc></url>
+  <url><loc>https://seoskill.dev/docs/reports/domain-rating</loc></url>
   <url><loc>https://seoskill.dev/docs/reports/domain-overview</loc></url>
   <url><loc>https://seoskill.dev/docs/reports/setup-check</loc></url>
   <url><loc>https://seoskill.dev/docs/reports/entity-readiness</loc></url>

apps/web/src/components/reports/ReportGuide.astro

@@ -246,7 +246,7 @@ const resultRows = [
 const lowerSentenceStart = (value: string) =>
   /^[A-Z][a-z]/.test(value) ? `${value[0]?.toLowerCase()}${value.slice(1)}` : value
 const evidenceIntro = `This ${page.noun} uses ${report.evidence
-  .map(lowerSentenceStart)
+  .map((value, index) => (index === 0 ? lowerSentenceStart(value) : value))
   .join(' ')}`
 const limitParagraphs = [
   report.caveats.join(' '),

apps/web/src/content/docs-nav.ts

@@ -36,6 +36,12 @@ export const docsNav: DocsNavEntry[] = [
     description:
       'Connect the permanent Semrush Version 3 key and run bounded keyword, domain, ranking-page and competitor research.',
   },
+  {
+    path: '/docs/ahrefs',
+    label: 'Ahrefs',
+    description:
+      'Connect an Ahrefs API v3 key and run bounded keyword, domain, competitor, Domain Rating and backlink research.',
+  },
   {
     path: '/docs/indexnow',
     label: 'IndexNow',