docs(privacy): document provider data boundaries

PRIVACY.md

@@ -1,13 +1,18 @@
 # Privacy policy
 
-Last updated: 18 July 2026
+Last updated: 23 July 2026
 
 This policy covers the official `seo` command-line tool, library, MCP server,
 and the seoskill.dev website.
 
 The current software runs on your machine. It does not create an SEO account,
-upload reports to an SEO service, or send your Google data to the project
-maintainer.
+upload reports to a hosted SEO service, or send reports or connected account
+data to the project maintainer.
+
+Local first describes where the software runs and stores its data. It does not
+mean every command works offline. A command can make a direct request from your
+machine to Google, a research provider, a site, or another service needed for
+the work you requested. The sections below explain what each request can send.
 
 ## Google data the software can access
 
@@ -34,12 +39,34 @@ The use of information received from Google APIs follows the [Google API
 Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy),
 including its Limited Use requirements.
 
+## When Search Console query text can leave your machine
+
+External enrichment is off by default. Three reports can send a limited part of
+their retained Search Console evidence to the connected research provider when
+you explicitly enable it:
+
+- `keyword-opportunities` can send selected query text for keyword metrics when
+  `includeExternal` is `true`;
+- `local-search-demand` can send selected local-intent query text for live
+  results when `includeSerps` is `true`; and
+- `pseo-opportunities` can send research seeds derived from retained query and
+  template evidence when `includeExternal` is `true`.
+
+These requests do not send Google OAuth tokens, Google account identity,
+Search Console property IDs, clicks, impressions, click-through rate,
+positions, or Google Analytics rows. The selected query or seed text is
+processed by the research provider under its own privacy policy. The report
+shows that external evidence was requested and keeps its meaning separate from
+first-party metrics.
+
 ## How Google data is protected
 
 The software stores project profiles, settings, OAuth tokens, cached API
-responses, logs, and saved reports in local user directories. It does not send
-Google user data to a hosted SEO account or database. Requests go directly from
-your machine to Google APIs over HTTPS.
+responses, logs, and saved reports in local user directories. It does not
+upload Google API responses to a hosted SEO account or project database.
+Google API requests go directly from your machine to Google over HTTPS. The
+only external research-provider use of selected query or seed text is the
+explicit enrichment described above.
 
 OAuth tokens use the operating system keychain when that option is enabled.
 The fallback token file and any bring-your-own OAuth client file are written
@@ -71,15 +98,95 @@ Run `seo cache clear --provider google-analytics` to remove cached Google
 Analytics responses immediately. Run `seo cache clear --provider gsc` to do
 the same for Search Console. Project profiles and reports that you deliberately
 save remain until you delete them with the relevant command or run
-`seo reset --yes`. The reset command removes all configuration, tokens, caches,
-logs, and saved data managed by the software.
-
-## Network requests
-
-Commands connect directly from your machine to the services needed for the
-work you request. These can include Google APIs, public pages and sitemaps you
-choose to crawl, and the npm registry for package update checks. Those services
-receive ordinary request data under their own privacy policies.
+`seo reset --yes`. The reset command removes Google tokens, local
+configuration, caches, logs, histories, and saved reports. Provider secrets in
+the system keychain need the provider-specific removal commands listed below.
+
+## Optional research provider requests
+
+DataForSEO requests can send the exact inputs needed for the selected
+operation. Depending on the 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
+[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.
+
+## Bing Webmaster requests
+
+Bing Webmaster is optional. If you connect it, the software sends your API key
+or OAuth bearer token, verified site URL, and the parameters needed for the
+report directly to Bing over HTTPS. Bing can return verified-site, traffic,
+crawl, query, page, and link data. The current report does not cache Bing
+responses. Microsoft processes the request under its
+[privacy statement](https://privacy.microsoft.com/privacystatement).
+
+## Other network requests
+
+Other commands can make these direct requests:
+
+- Crawls request the public pages, sitemaps, robots files, and agent files you
+  select. External-link checks can request linked third-party pages. Browser
+  rendering can also load scripts, images, fonts, and other resources embedded
+  by a page.
+- Chrome UX Report requests send the requested URL or origin, form factor,
+  metrics, and your API key to Google.
+- Search status checks request Google's public incident feed without sending a
+  site or property.
+- A live IndexNow submission sends the host, changed URLs, key, and public key
+  location to IndexNow. A dry run does not submit them. IndexNow handles the
+  request under its [terms](https://www.indexnow.org/terms).
+- Package update checks can request current package information from the npm
+  registry.
+- Anonymous usage events can be sent to seoskill.dev as described in the next
+  section.
+
+The remote service receives ordinary network metadata in addition to the
+listed inputs and handles it under its own terms and privacy policy.
+
+When an agent or MCP client runs the software, that client may send tool
+inputs, report output, or conversation context to its chosen model provider.
+That transfer is controlled by the client and model service, not by the local
+`seo` process. Check the privacy settings and policy of the agent you use.
+
+## 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.
+
+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 local configuration, caches,
+histories, spend records, logs, and saved reports. It does not clear
+DataForSEO, Bing, or IndexNow secrets from the system keychain.
 
 ## Anonymous tool usage
 
@@ -134,25 +241,35 @@ stored by the local software.
 
 ## Sharing and sale
 
-The project maintainer does not receive or sell the Google user data processed
-by the local software. The software sends data to Google only as needed to make
-the API request you initiated. It sends crawl requests to the public sites you
-ask it to inspect.
+The project maintainer does not receive or sell the reports, connected account
+data, or provider request data processed by the local software. A service you
+choose receives only the request inputs needed for the operation you start, as
+described above.
 
 No local report is shared with another person or service unless you export,
-copy, publish, or transmit it yourself.
+copy, publish, transmit, or pass it to an agent or application yourself.
+
+## Removing access and local data
 
-## Removing Google access
+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 local files managed by the software.
 
-You can also revoke the app from your [Google Account connections](https://myaccount.google.com/connections).
-Deleting local files does not delete data held by Google, npm, GitHub, a site
-you crawled, or your operating system backups.
+You can also revoke the app from your
+[Google Account connections](https://myaccount.google.com/connections).
+Deleting local files does not delete data already held by Google, a research
+provider, Bing, IndexNow, npm, GitHub, a site you crawled, an agent or model
+provider, or your operating system backups.
 
 ## Changes to this policy
 
-This policy will change if the product starts collecting data or adds a hosted
-service. The date at the top will be updated when that happens. Earlier versions
-remain available in the public Git history.
+This policy will change when a collection, storage, retention, network, or
+hosted-service boundary changes materially. The date at the top will be updated
+when that happens. Earlier versions remain available in the public Git history.
 
 ## Privacy questions
 

README.md

@@ -83,8 +83,6 @@ technical report before connecting Google.
 Running `seo help` shows the shape of the tool:
 
 ```txt
-seo v0.2.15
-
 Run SEO audits, find what needs fixing, and ship the changes with your agent.
 
 Start here
@@ -651,15 +649,17 @@ paths, including OAuth testing-mode limits.
 ### Does my site data stay on my machine?
 
 Yes. Reports, project profiles, Google tokens, crawls, and caches stay in your
-local config directory. The CLI only makes the network requests needed to fetch
-your site and call the Google APIs you connect.
-
-SEO data never leaves your machine. The CLI sends anonymous usage events such
-as the event name, report id, tool version, agent, OS, architecture, Node major,
-and install week. It never sends URLs, identifiers, report data, or Google data.
-Disable telemetry with `DO_NOT_TRACK=1` or `seo telemetry disable`. Read the
-[full telemetry details](https://seoskill.dev/telemetry) and the
-[public aggregate stats](https://seoskill.dev/stats).
+local config directory. Local first does not mean offline. A command can
+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
+[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.
 
 ### Do I need a Google API key?
 
@@ -694,7 +694,7 @@ vulnerabilities privately through the process in [SECURITY.md](SECURITY.md).
 - [CLI commands](https://seoskill.dev/docs/cli)
 - [Crawler](https://seoskill.dev/docs/crawler)
 - [Reports and data](https://seoskill.dev/docs/reports)
-- [Keyword and competitor research](https://seoskill.dev/docs/research-providers)
+- [Research providers](https://seoskill.dev/docs/research-providers)
 - [MCP and agents](https://seoskill.dev/docs/agents)
 - [AI-search evidence](https://seoskill.dev/docs/ai-search)
 - [Privacy policy](https://seoskill.dev/privacy)

SECURITY.md

@@ -24,12 +24,20 @@ and caches stay on the machine running the command. Access and refresh tokens
 use the operating-system keychain when enabled; fallback token files and local
 credential files use private file permissions.
 
+Local first does not mean offline. Crawls, connected accounts, research
+providers, Chrome UX Report, IndexNow, package checks, and anonymous telemetry
+can make the direct network requests described in the
+[privacy policy](https://seoskill.dev/privacy).
+
 Desktop OAuth client credentials are not confidential secrets. User tokens,
 provider API keys, and analytics data are confidential and must never be
 committed, pasted into issues, or included in fixtures.
 
-Use `seo privacy` to inspect local storage and `seo reset --yes` to remove it.
-Google grants can also be revoked at
+Use `seo privacy` to inspect local files. Remove saved provider secrets with
+their disconnect or removal commands before `seo reset --yes`; reset clears
+Google tokens and the local config, cache, and log directories but does not
+currently clear provider secrets from the operating-system keychain. Google
+grants can also be revoked at
 <https://myaccount.google.com/connections>.
 
 ## Maintainer checks

TERMS.md

@@ -1,6 +1,6 @@
 # Terms of use
 
-Last updated: 10 July 2026
+Last updated: 23 July 2026
 
 These terms cover the official `seo` command-line tool, library, MCP server,
 documentation, and seoskill.dev website.
@@ -35,6 +35,12 @@ Your use of Google APIs is also subject to Google's terms and policies. Google
 can change API behaviour, quotas, scopes, or availability without notice to
 this project.
 
+Optional research providers, Bing Webmaster, Chrome UX Report, and IndexNow are
+also controlled by their respective operators. A provider can charge for a
+request, retain task data, change its prices or limits, or withdraw a feature.
+Review the provider's current terms, privacy policy, and report cost evidence
+before sending sensitive inputs or starting broad paid work.
+
 The software can request public websites, run browser tooling, and use package
 registries or operating system services. Those products are controlled by
 their respective operators. The project is not responsible for their content,

apps/web/src/content/docs/docs/getting-started.md

@@ -132,8 +132,10 @@ prints the paths used for profiles, tokens, caches, and saved reports on your
 operating system.
 
 Use `seo auth logout` to delete local Google tokens. Use `seo reset` only when
-you want to remove all local SEO data. The [privacy policy](/privacy)
-documents every storage and network boundary.
+you want to remove local configuration, caches, histories, logs, and saved
+reports. Disconnect provider credentials and remove saved IndexNow keys first
+if they are stored in the system keychain. The [privacy policy](/privacy)
+documents every storage, deletion, and network boundary.
 
 ## Add research data when the question needs it
 

apps/web/src/content/docs/docs/research-providers.mdx

@@ -76,6 +76,37 @@ report includes cache hit, miss or bypass state, observation time, estimated
 cost, actual cost and provider task ids. Use `refresh: true` only when the
 decision needs newer provider evidence.
 
+## Know what a provider request sends
+
+The software stores provider credentials, caches, histories and spend records
+locally. A live provider request still sends the inputs needed for that
+operation directly to the provider.
+
+| Operation | Inputs sent to DataForSEO |
+| --- | --- |
+| Keyword, result and domain research | Keywords or seeds, domains or URLs, market, location, device, filters and limits required by the report. |
+| Link research | The target domain or URL, provider filters and result limits. |
+| Indexed AI mention research | Target names and aliases, surface, market and result limits. |
+| Fixed AI prompt observation | The full prompt, selected model, country, web search setting and output limit. |
+| First-party enrichment | Selected Search Console query text or a derived research seed, only when `includeExternal` or `includeSerps` is explicitly enabled. |
+
+First-party enrichment does not send Google OAuth tokens, Google account
+identity, Search Console property IDs, clicks, impressions, click-through rate,
+positions, or Google Analytics rows. The report keeps provider estimates and
+first-party metrics separate.
+
+DataForSEO processes live inputs and responses under its
+[privacy policy](https://dataforseo.com/privacy-policy). As of 23 July 2026,
+that policy says API task data is stored for 365 days. Local cache removal and
+`seo providers dataforseo disconnect` do not delete provider-side task data.
+Use the disconnect command to remove saved credentials, then
+`seo reset --yes` to remove local configuration, caches, histories, spend
+records, logs and saved reports. Environment credentials remain under the
+control of your shell or runtime.
+
+Local DataForSEO, Semrush and Ahrefs file imports are different. They are read
+from disk and are not uploaded to a provider or the project maintainer.
+
 ## Discover the research reports
 
 The normal CLI and MCP discovery flow exposes the same reports:

apps/web/src/pages/cookies.astro

@@ -4,11 +4,11 @@ import PolicyLayout from '@/layouts/PolicyLayout.astro'
 
 <PolicyLayout
   title="Cookie policy"
-  description="How seoskill.dev uses cookie-free Clicky analytics without receiving reports, tokens, or Google data from the local SEO CLI."
-  dateModified="2026-07-14"
+  description="How seoskill.dev uses cookie-free Clicky analytics without receiving local reports, tokens, or connected account data."
+  dateModified="2026-07-23"
 >
   <h1>Cookie policy</h1>
-  <p>Last updated: 14 July 2026</p>
+  <p>Last updated: 23 July 2026</p>
   <p>
     The seoskill.dev website uses Clicky to count visits and see which pages
     people use. Clicky tracking cookies are disabled in the website code.
@@ -17,8 +17,8 @@ import PolicyLayout from '@/layouts/PolicyLayout.astro'
     Clicky receives normal browser and request information such as the page,
     referrer, device, and IP address under its
     <a href="https://clicky.com/terms/privacy" target="_blank" rel="noreferrer">privacy policy</a>.
-    It does not receive your local SEO reports, Google tokens, or Google API
-    responses.
+    It does not receive your local reports, tokens, connected account data, or
+    provider responses.
   </p>
   <p>
     The site is served through Cloudflare. Cloudflare may also process normal

apps/web/src/pages/privacy.astro

@@ -5,8 +5,8 @@ import { Content as PrivacyPolicy } from '../../../../PRIVACY.md'
 
 <PolicyLayout
   title="Privacy policy"
-  description="How the local SEO CLI handles Google access, local data, network requests, and the seoskill.dev website."
-  dateModified="2026-07-16"
+  description="How the local SEO software handles connected accounts, provider requests, local data, telemetry, and the seoskill.dev website."
+  dateModified="2026-07-23"
 >
   <PrivacyPolicy />
 </PolicyLayout>