analytics_ops 0.2.0 → 0.3.0

data/docs/configuration.md

@@ -10,10 +10,15 @@ property:
 analytics-ops setup --service-account /absolute/path/to/service-account.json
 ```
 
-Setup writes only a quoted property ID under the `production` profile. It
-will reuse a matching file but will not overwrite an existing profile that
+Setup writes only a quoted property ID under the selected profile. It reuses a
+matching profile, safely appends a missing profile, and fills the untouched
+Rails-generator placeholder. It will not overwrite an existing profile that
 targets another property.
 
+```bash
+analytics-ops setup --profile client_b --connection client_b
+```
+
 ## Smallest valid file
 
 ```yaml
@@ -38,7 +43,7 @@ analytics-ops audit
 The default path is `config/analytics_ops.yml`; the default profile is
 `production`. Change them with `--config` and `--profile`.
 
-## Complete example
+## Managed-settings example
 
 All identifiers below are fake:
 
@@ -55,7 +60,7 @@ profiles:
         default_uri: "https://www.example.test"
 
         # Accepted only as an explicit experimental declaration.
-        # Version 0.2.0 reports a finding and does not apply this setting.
+        # Version 0.3.0 reports a finding and does not apply this setting.
         enhanced_measurement:
           enabled: true
           experimental: true
@@ -95,7 +100,7 @@ profiles:
       - email_redaction_enabled
       - consent_mode_reviewed
 
-    # Explicit declaration only in 0.2.0; never silently applied.
+    # Explicit declaration only in 0.3.0; never silently applied.
     google_signals:
       state: disabled
       experimental: true
@@ -109,6 +114,8 @@ profiles:
 `stream_id`. For a web stream, `default_uri` may be an absolute HTTP or
 HTTPS URI without embedded credentials. Analytics Ops can update an existing
 web stream URI; it does not automatically create or delete streams.
+Two local stream names cannot target the same `stream_id`; that ambiguity is
+rejected while loading configuration.
 
 ### Retention
 
@@ -157,6 +164,112 @@ Identity is `parameter_name`. Scope, unit, and restricted-data classification
 are treated as immutable; Analytics Ops will not archive and recreate a
 conflicting metric.
 
+## Optional reporting and organization fields
+
+These fields improve reporting but do not create an ordinary mutation plan.
+
+### Labels
+
+Labels help identify profiles in a multi-property portfolio:
+
+```yaml
+labels:
+  client: Example client
+  brand: Example store
+  region: North America
+```
+
+A profile can contain up to 16 short label pairs. Labels are local and are
+never written to Google.
+
+### Saved reports
+
+Save a reusable Data API definition:
+
+```yaml
+reports:
+  purchases_by_country:
+    dimensions: [country, eventName]
+    metrics: [eventCount, totalUsers]
+    dimension_filter:
+      field: eventName
+      match_type: exact
+      value: purchase
+    order_bys:
+      - metric: eventCount
+        desc: true
+    limit: 500
+```
+
+`kind` defaults to `standard`. Standard reports default to the previous 28
+complete days. A realtime recipe uses `kind: realtime` and cannot contain date
+ranges or offsets.
+
+Definitions can contain nested boolean filters, in-list and null filters,
+numeric comparisons, up to four date ranges, and up to ten order clauses.
+Runtime validation is stricter than YAML shape alone: filters and ordering
+must reference selected fields. See [Reports](reports.md).
+
+### Health policy
+
+```yaml
+health:
+  expected_events: [page_view, purchase]
+  minimum_sessions: 100
+  traffic_drop_percent: 40
+  key_event_drop_percent: 30
+  unassigned_percent: 10
+  not_set_percent: 10
+```
+
+Every field is optional. See [Analytics health](health.md) for defaults and
+meaning.
+
+## Optional experimental read features
+
+Experimental sections require the literal acknowledgement
+`experimental: true`. They never become ordinary plan operations.
+
+### Governance
+
+```yaml
+governance:
+  experimental: true
+  enhanced_measurement_required: true
+  email_redaction_required: true
+  reporting_identity: blended
+  bigquery_link_required: true
+  expected_channel_groups:
+    - Primary channel group
+```
+
+The governance command reads Alpha Admin resources and checks only the
+expectations present here. See [Governance checks](governance.md).
+
+### BigQuery and funnels
+
+```yaml
+bigquery:
+  experimental: true
+  project_id: example-analytics-project
+  dataset: analytics_123456789
+  location: US
+  maximum_bytes_billed: 1000000000
+
+funnels:
+  checkout:
+    experimental: true
+    steps:
+      - name: Viewed product
+        event_name: view_item
+      - name: Purchased
+        event_name: purchase
+```
+
+BigQuery is an optional dependency and every query is cost-capped. Funnel
+names are local. Each funnel has 2 through 10 unique, ordered steps. See
+[BigQuery reports and funnels](bigquery.md).
+
 ## Environment variables
 
 Only the literal form `${UPPER_CASE_NAME}` is expanded, and interpolation

data/docs/google-client-compatibility.md

@@ -10,6 +10,10 @@ second HTTP stack and does not expose generated Google objects publicly.
 | `google-analytics-admin` | `~> 0.8.0` | 0.8.0 |
 | `google-analytics-data` | `~> 0.9.0` | 0.9.0 |
 | `googleauth` | `~> 1.12` | 1.17.1 |
+| `mcp` | `~> 0.25.0` | 0.25.0 |
+
+Optional BigQuery support uses `google-cloud-bigquery ~> 1.64`. It is not a
+runtime dependency and is never loaded by normal Analytics commands.
 
 The reviewed lockfile resolves these generated transports:
 
@@ -44,11 +48,27 @@ protobuf classes for:
 - custom-metric restricted cost/revenue enum translation
 - update web data-stream default URI
 - `run_report`, `batch_run_reports`, and `run_realtime_report`
+- recursive Data API filters, metadata, and `check_compatibility`
+- Enhanced Measurement and data-redaction settings
+- reporting identity and attribution settings
+- channel groups, calculated metrics, event create/edit rules, and BigQuery
+  links
+- bounded account/property change history
+- aggregate Data Access reports
 
 The tests also prove enum mappings and normalization into immutable gem-owned
 values without making network requests. Service-account tests exercise the
 official `Google::Auth::ServiceAccountCredentials` loader with generated fake
-keys and verify the exact read/edit scopes.
+keys and verify the exact Analytics read/edit and optional BigQuery read-only
+scopes.
+
+Optional BigQuery contract tests prove fixed parameterized SQL, dry-run
+estimation, `maximum_bytes_billed`, location selection, bounded result
+normalization, and aggregate funnel output without contacting Google.
+
+MCP contract tests use the official Ruby SDK to prove the exact tool allowlist,
+strict input validation, structured output, redacted errors, lazy credential
+loading, and read-only/non-destructive annotations.
 
 ## Updating a Google client
 

data/docs/governance.md

@@ -0,0 +1,93 @@
+# Governance checks
+
+Governance commands read broader GA4 administration settings. They are
+experimental because Google exposes several of these resources through its
+Alpha Admin API. They do not change GA4.
+
+Normal reporting does not require this feature.
+
+## Governance audit
+
+```bash
+analytics-ops governance
+analytics-ops governance --json
+```
+
+The snapshot includes:
+
+- Enhanced Measurement and data-redaction settings for each web stream
+- reporting identity and attribution settings
+- channel groups and calculated metrics
+- event create and edit rules for each web stream
+- existing BigQuery links
+
+Add only the expectations you care about:
+
+```yaml
+profiles:
+  production:
+    property_id: "123456789"
+
+    governance:
+      experimental: true
+      enhanced_measurement_required: true
+      email_redaction_required: true
+      query_parameter_redaction_required: true
+      reporting_identity: blended
+      bigquery_link_required: true
+      expected_channel_groups:
+        - Primary channel group
+      expected_calculated_metrics:
+        - Average order value
+      expected_event_create_rules:
+        - purchase_completed
+      expected_event_edit_rules:
+        - Normalize campaign
+```
+
+`experimental: true` is required so Alpha behavior is never enabled by
+accident. Exit status `2` means a configured expectation did not match.
+
+## Change history
+
+```bash
+analytics-ops changes
+```
+
+Google requires the `analytics.edit` OAuth scope to read change history even
+though this command performs no write. Analytics Ops requests that scope only
+for this command and guarded `apply`.
+
+The result is deliberately de-identified. It returns the time, actor type,
+changed resource, and action. It omits user email addresses and full
+before/after resource bodies. Up to 100 recent events from the previous 30
+days are requested.
+
+## Aggregate Data API access
+
+```bash
+analytics-ops access
+```
+
+This requests only `accessDateHour` and
+`dataApiQuotaPropertyTokensConsumed`. Those aggregate fields work with
+ordinary GA4 properties and do not request user email or IP address.
+
+Google limits Data Access reports to GA4 Administrators. A Viewer or Editor
+service account may therefore receive a permission error for this one command.
+Normal reports, health, audit, and governance do not need Administrator.
+
+## Safety and limitations
+
+- These commands never create, update, delete, or reorder resources.
+- Event rules are read from each web stream, not from the property root.
+- Alpha methods can change or disappear in a future Google client.
+- A failed capability stops the governance snapshot instead of pretending the
+  missing data is compliant.
+- `apply` does not manage any of these experimental settings.
+
+Official references:
+
+- [Admin API overview](https://developers.google.com/analytics/devguides/config/admin/v1)
+- [Change history](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/accounts/searchChangeHistoryEvents)
+- [Data Access reports](https://developers.google.com/analytics/devguides/config/admin/v1/access-api)

data/docs/health.md

@@ -0,0 +1,82 @@
+# Analytics health
+
+`health` is a read-only, deterministic check of whether analytics looks
+healthy. It does not use AI to invent a score, and it never changes GA4.
+
+Start with:
+
+```bash
+analytics-ops health
+```
+
+It compares the previous 28 complete days with the 28 days before them and
+checks:
+
+- minimum traffic
+- large session or key-event drops
+- unusually high `Unassigned` or `(not set)` acquisition traffic
+- events you expected but did not receive
+- Google thresholding or sampling notices
+- low remaining Data API quota
+- drift in configuration managed by Analytics Ops
+
+Exit status `0` means no configured problem was found. Status `2` means one or
+more findings need review; it is not a crash.
+
+## Choose the period
+
+```bash
+analytics-ops health --last 7
+analytics-ops health --from 2026-07-01 --to 2026-07-14
+```
+
+Health always compares the selected period with an equally long preceding
+period, even when `--compare` is not written.
+
+## Set your own policy
+
+All settings are optional:
+
+```yaml
+version: 1
+
+profiles:
+  production:
+    property_id: "123456789"
+
+    health:
+      expected_events:
+        - page_view
+        - purchase
+      minimum_sessions: 100
+      traffic_drop_percent: 40
+      key_event_drop_percent: 30
+      unassigned_percent: 10
+      not_set_percent: 10
+```
+
+Percent values are from `0` through `100`. A zero drop threshold means “warn
+about any real drop”; equal periods do not produce a false warning.
+
+Choose expectations that fit the property. A new site may legitimately have
+few sessions, and a rare purchase event may not occur every week.
+
+## Check every property
+
+```bash
+analytics-ops portfolio health
+analytics-ops portfolio health --last 7 --concurrency 4
+```
+
+Each property uses its own profile and named connection. One inaccessible
+property is reported as an isolated error instead of hiding results from the
+others. Concurrency is bounded from `1` through `8`.
+
+## Important limits
+
+Health is an operational signal, not proof of revenue, consent, or tracking
+correctness. GA4 can delay, model, sample, threshold, or omit data. The checks
+cannot see visitors blocked before an event reaches Google.
+
+Use `overview`, `report`, and your tagging debugger to investigate a finding.
+Use `audit` to inspect configuration drift in detail.

data/docs/live-smoke-test.md

@@ -46,7 +46,7 @@ gem "analytics_ops",
 ```
 
 Run `bundle install`. `bundle info analytics_ops` must show the local checkout
-and version `0.2.0`.
+and version `0.3.0`.
 
 ### Preserve an existing configuration
 
@@ -72,9 +72,10 @@ bundle exec analytics-ops setup \
   --service-account /absolute/path/outside/repositories/service-account.json
 ```
 
-Analytics Ops validates the key, verifies both APIs, and remembers only its
-absolute path in `~/.config/analytics_ops/connection.json` with mode `0600`.
-The key is not copied.
+Analytics Ops validates the key, verifies both APIs, and remembers a named
+connection containing only its absolute path in
+`~/.config/analytics_ops/connection.json` with mode `0600`. The key is not
+copied.
 
 Run plain setup once more to verify the remembered connection:
 
@@ -89,6 +90,8 @@ bundle exec analytics-ops version
 bundle info analytics_ops
 bundle exec analytics-ops doctor
 bundle exec analytics-ops overview
+bundle exec analytics-ops overview --last 7 --compare
+bundle exec analytics-ops portfolio
 bundle exec analytics-ops report traffic --json
 bundle exec analytics-ops realtime
 bundle exec analytics-ops audit
@@ -127,15 +130,15 @@ service account if Analytics Ops will remain in use. For a temporary-only
 test, remove the connection file and revoke the downloaded key in Google
 Cloud.
 
-Keep the local path dependency until `0.2.0` is published. After publication,
+Keep the local path dependency until `0.3.0` is published. After publication,
 replace it with:
 
 ```ruby
-gem "analytics_ops", "~> 0.2", group: :development
+gem "analytics_ops", "~> 0.3", group: :development
 ```
 
 Run `bundle install`, then confirm `bundle info analytics_ops` resolves
-version `0.2.0` from RubyGems.
+version `0.3.0` from RubyGems.
 
 ## Release gate
 
@@ -146,13 +149,13 @@ Require all of the following:
 - `bin/check`, package inspection, and `git diff --check` passed.
 - Documentation and changelog describe the released behavior.
 - The gem worktree is clean and the release commit is on `origin/master`.
-- Version and changelog both say `0.2.0`.
+- Version and changelog both say `0.3.0`.
 
 Then create and push the annotated tag:
 
 ```bash
-git tag -a v0.2.0 -m "Release Analytics Ops 0.2.0"
-git push origin v0.2.0
+git tag -a v0.3.0 -m "Release Analytics Ops 0.3.0"
+git push origin v0.3.0
 ```
 
 The tag workflow verifies and publishes through RubyGems Trusted Publishing.

data/docs/rails.md

@@ -14,10 +14,9 @@ Active Support.
 
 ```bash
 bundle install
+bin/rails generate analytics_ops:install
 bundle exec analytics-ops setup \
-  --profile development \
   --service-account /absolute/path/to/service-account.json
-bin/rails generate analytics_ops:install
 ```
 
 The generator creates only:
@@ -25,26 +24,39 @@ The generator creates only:
 - `config/analytics_ops.yml`
 - `bin/analytics-ops` with executable mode
 
-If setup already created the configuration, the generator preserves it and
-adds only the binstub. It never asks to overwrite the selected property.
+The order is flexible:
+
+- Generator first: setup safely replaces the untouched placeholder.
+- Setup first: the generator preserves the valid configuration and adds only
+  the binstub.
 
-The generated file has a minimal `development` profile and a fake-safe
-property-ID placeholder. It contains no active stream, retention, key-event,
-dimension, or metric policy, so installation alone cannot produce a mutation
-plan. Add managed settings only after reviewing the configuration guide. Add
-a profile matching another Rails environment, or set `ANALYTICS_OPS_PROFILE`.
+The generated file has the same minimal `production` profile used by the CLI.
+It contains no active stream, retention, key-event, dimension, or metric
+policy, so installation alone cannot produce a mutation plan. Add managed
+settings only after reviewing the configuration guide.
 
 ## Rake tasks
 
 ```bash
 bin/rake analytics:doctor
 bin/rake analytics:overview
+bin/rake analytics:portfolio
+bin/rake analytics:health
+bin/rake analytics:governance
+bin/rake analytics:access
 bin/rake analytics:audit
 bin/rake analytics:plan
 bin/rake analytics:verify
 bin/rake 'analytics:report[traffic_acquisition]'
+bin/rake 'analytics:raw[event_counts]'
+bin/rake 'analytics:funnel[checkout]'
 ```
 
+`raw` and `funnel` require the optional BigQuery configuration and
+`google-cloud-bigquery` dependency. `governance` and `access` are experimental
+read-only Admin API tasks. See [Governance checks](governance.md) and
+[BigQuery reports and funnels](bigquery.md).
+
 `analytics:plan` writes `tmp/analytics_ops-plan.json`. Override task inputs
 without changing application code:
 
@@ -55,6 +67,10 @@ ANALYTICS_OPS_PLAN=tmp/production-ga4-plan.json \
 bin/rake analytics:plan
 ```
 
+Rails tasks use the profile selected by `analytics-ops use`. Set
+`ANALYTICS_OPS_PROFILE` only for an explicit one-run override; Rails
+environment names no longer silently select a different profile.
+
 There is intentionally no `analytics:apply` Rake task. Apply a reviewed file
 with the explicit CLI: