seo 0.2.4 → 0.2.6

package/PRIVACY.md

@@ -1,6 +1,6 @@
 # Privacy policy
 
-Last updated: 14 July 2026
+Last updated: 16 July 2026
 
 This policy covers the official `seo` command-line tool, library, MCP server,
 and the seoskill.dev website.
@@ -18,7 +18,7 @@ read-only access to:
   you connected;
 - Search Console properties, performance data, and URL Inspection data you can
   already access; and
-- Google Analytics 4 accounts, properties, and report data you can already
+- Google Analytics accounts, properties, and report data you can already
   access.
 
 The software uses this data to list properties, run the report you requested,
@@ -53,9 +53,46 @@ 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.
 
-The CLI does not include project-controlled usage telemetry. Installing the
-package through npm or using GitHub is covered by the policies of those
-services.
+## Anonymous tool usage
+
+Anonymous usage telemetry is enabled by default with a one-time first-run
+notice. It describes use of the tool, not the site or Google data being
+analysed. Events can contain only a fixed event name, public report identifier,
+package version, detected agent category, operating system, architecture, Node
+major version, first-run ISO week, wire schema version, and a fixed error
+category for failed reports.
+
+Telemetry never contains a user ID, machine ID, UUID, fingerprint, audited
+domain, URL, hostname, page content, report content, Search Console or Google
+Analytics response, Google property ID, token, secret, file path, username,
+local hostname, raw error message, IP address, or location. The complete event
+and field catalogue is published at
+[seoskill.dev/telemetry](https://seoskill.dev/telemetry).
+
+Once-only event state stays in a private local file in the existing SEO config
+directory. The telemetry endpoint accepts only the published fixed schema and
+writes those fields to a dedicated Cloudflare D1 table. The server adds only
+the UTC receipt month, such as `2026-07`, so it can publish monthly totals
+without storing an exact request time. The table has no account or identity
+column. It does not use KV, R2, or Analytics Engine. Worker request logging is
+disabled. The ingest code does not read request IP or Cloudflare location
+fields, and neither is written to D1. Cloudflare still handles the ordinary
+network request at its edge.
+
+Disable all telemetry network calls with `seo telemetry disable`,
+`DO_NOT_TRACK=1`, `SEOSKILL_TELEMETRY_DISABLED=1`, or
+`SEO_TELEMETRY_DISABLED=1`. It is automatically disabled in common CI
+environments. Use `seo telemetry status` to inspect the effective setting and
+`seo telemetry enable` to turn the local setting back on. Environment and CI
+overrides always win.
+
+Aggregate event counts are public at
+[seoskill.dev/stats](https://seoskill.dev/stats). They are described as
+installs, active machines, and audits, never users. One person can have several
+installs, and clearing local state creates a new install.
+
+Installing the package through npm or using GitHub is covered by the policies
+of those services.
 
 The seoskill.dev website uses [Clicky](https://clicky.com/terms/privacy) to
 count visits and see which pages people use. Tracking cookies are disabled in

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">SEO Skill</h1>
 
 <p align="center">
-  The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and GA4 data.
+  The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and Google Analytics data.
 </p>
 
 <p align="center">
@@ -47,7 +47,7 @@ clicks, and catch regressions after a release.
 
 - People running their own sites who want a clear audit and a ranked list of
   fixes, without learning a heavy dashboard.
-- AI agents that need real crawl, Search Console, and GA4 evidence through MCP
+- AI agents that need real crawl, Search Console, and Google Analytics evidence through MCP
   and one packaged SEO skill instead of screenshots or guesses.
 - Developers who want to embed the same report engine in a script, a CI job, or
   a TypeScript app.
@@ -63,7 +63,7 @@ seo report
 ```
 
 The setup walks you through Google sign-in, your Search Console property, an
-optional GA4 property, and a local project profile. Public releases can include
+optional Google Analytics property, and a local project profile. Public releases can include
 the shared Google app. If it is unavailable in your build, setup guides you
 through adding your own desktop OAuth client.
 
@@ -77,7 +77,7 @@ technical report before connecting Google.
 Running `seo help` shows the shape of the tool:
 
 ```txt
-seo v0.2.4
+seo v0.2.6
 
 Run SEO audits, find what needs fixing, and ship the changes with your agent.
 
@@ -140,7 +140,7 @@ The point of a report is to be defensible, so the design keeps a few rules:
 ## Everyday use
 
 `seo start` can save a project profile, which is a local shortcut for a site,
-Search Console property, GA4 property, and brand terms. If you have one default
+Search Console property, Google Analytics property, and brand terms. If you have one default
 project, most commands need no flags.
 
 ```sh
@@ -173,6 +173,14 @@ property with `seo start`.
 
 Run `seo help` for the short path or `seo help all` for the full command list.
 
+Google Analytics commands sit under their provider namespace. List the properties available
+to the connected account, then run a report with the property you need:
+
+```sh
+seo analytics google properties
+seo analytics google report --property 123456789 --dimensions landingPage --metrics sessions,totalUsers
+```
+
 ## Crawl a site
 
 Run a readable technical crawl, the base of any technical SEO audit:
@@ -212,7 +220,7 @@ terminal prose.
 evidence so an agent can choose its next call without loading every raw report.
 Use `--full` only when a script needs the complete report object.
 
-When a CI job needs Search Console or GA4 data, give it a Google service
+When a CI job needs Search Console or Google Analytics data, give it a Google service
 account JSON key through its secret store. The service account needs access to
 the exact properties it will query. This GitHub Actions step runs without a
 browser or a copied local token:
@@ -227,7 +235,7 @@ browser or a copied local token:
 ```
 
 The [Google data guide](https://seoskill.dev/docs/google) covers Search
-Console and GA4 permissions, mounted secret files, and how to check the active
+Console and Google Analytics permissions, mounted secret files, and how to check the active
 identity safely.
 
 Agents can discover and run the same report catalog as MCP without starting a
@@ -368,9 +376,9 @@ seo reset
 `seo auth status` shows the active storage mode. Power users can choose it with
 `seo auth storage --keychain` or `seo auth storage --file`.
 
-Power users can bring their own Google OAuth client. See
-[getting started](https://seoskill.dev/docs/getting-started) for the available
-auth paths.
+Power users can bring their own Google OAuth client or use a service account in
+CI. The [Google data guide](https://seoskill.dev/docs/google) covers both auth
+paths, including OAuth testing-mode limits.
 
 ## Common questions
 
@@ -378,13 +386,19 @@ auth paths.
 
 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. There is no hosted backend,
-account, or telemetry service.
+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).
 
 ### Do I need a Google API key?
 
 No. `seo start` uses a normal Google sign-in for read-only Search Console and
-GA4 access. Public releases can include a shared desktop OAuth client, and if
+Google Analytics access. Public releases can include a shared desktop OAuth client, and if
 your build does not have one, setup helps you add your own. You can also run a
 local technical crawl with no Google connection at all.
 
@@ -415,6 +429,8 @@ vulnerabilities privately through the process in [SECURITY.md](SECURITY.md).
 - [MCP and agents](https://seoskill.dev/docs/agents)
 - [AI-search evidence](https://seoskill.dev/docs/ai-search)
 - [Privacy policy](https://seoskill.dev/privacy)
+- [Anonymous telemetry](https://seoskill.dev/telemetry)
+- [Public usage stats](https://seoskill.dev/stats)
 - [Terms of use](https://seoskill.dev/terms)
 - [Security policy](https://seoskill.dev/security)
 - [Contributing](CONTRIBUTING.md)