analytics_ops 0.1.0 → 0.2.0

data/docs/live-smoke-test.md

@@ -0,0 +1,159 @@
+# Live read-only smoke test
+
+Use this guide before releasing Analytics Ops or when checking it in a real
+application. The test reads Google Analytics and writes local setup files. It
+never changes GA4.
+
+## What you need
+
+| Item | Purpose | Fake example |
+| --- | --- | --- |
+| Google account | Your human login for Cloud and GA4 administration | `operator@example.test` |
+| GA4 account | Owns one or more GA4 properties | Account ID `100000001` |
+| GA4 property | Holds the configuration and reports being tested | Property ID `123456789` |
+| Google Cloud project | Owns API enablement, quota, and the service account | `example-analytics-project` |
+| Service account | The non-human identity Analytics Ops uses | `analytics-ops@example-project.iam.gserviceaccount.com` |
+
+Cloud IAM access and GA4 access are separate. The service account does not
+need a broad Cloud role, but its email must be added inside GA4 Access
+Management.
+
+A normal API key cannot read private GA4 data or change GA4 settings.
+
+## Prepare Google once
+
+1. In the Cloud project, enable:
+   - Google Analytics Admin API
+   - Google Analytics Data API
+2. Open [Google Cloud service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts).
+3. Create **Analytics Ops Local** without broad Cloud IAM roles.
+4. Create a JSON key and save it outside all repositories.
+5. In GA4, open **Admin → Account access management → Add users**.
+6. Add the service-account email as Viewer for read-only use or Editor for
+   future reviewed applies.
+
+No Google Cloud CLI, browser authorization, consent screen, OAuth client, or
+test-user setup is used.
+
+## Test the checkout through a real app
+
+Temporarily point the host application's Gemfile at the local gem:
+
+```ruby
+gem "analytics_ops",
+    path: "/absolute/path/to/analytics_ops",
+    group: :development
+```
+
+Run `bundle install`. `bundle info analytics_ops` must show the local checkout
+and version `0.2.0`.
+
+### Preserve an existing configuration
+
+Setup never overwrites a conflicting profile. If
+`config/analytics_ops.yml` already exists, hold it safely outside the
+application while testing:
+
+```bash
+analytics_smoke_backup="$(mktemp -d)"
+cp config/analytics_ops.yml "$analytics_smoke_backup/original.yml"
+mv config/analytics_ops.yml "$analytics_smoke_backup/held.yml"
+```
+
+Do not print the file. Production identifiers and environment conventions do
+not belong in public test output.
+
+### Connect once
+
+Use the downloaded key without printing its contents:
+
+```bash
+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.
+
+Run plain setup once more to verify the remembered connection:
+
+```bash
+bundle exec analytics-ops setup
+```
+
+### Run every read-only check
+
+```bash
+bundle exec analytics-ops version
+bundle info analytics_ops
+bundle exec analytics-ops doctor
+bundle exec analytics-ops overview
+bundle exec analytics-ops report traffic --json
+bundle exec analytics-ops realtime
+bundle exec analytics-ops audit
+```
+
+Empty reports are acceptable for a property with little traffic.
+Authentication errors, authorization errors, malformed output, crashes, and
+Google-client errors are failures.
+
+`audit` exit status `0` means the declared state converges. Exit status `2`
+means drift was found. Both are successful read-only smoke-test outcomes.
+
+During the test:
+
+- Never run `analytics-ops apply`.
+- Do not create a plan for application.
+- Never commit the service-account JSON, the connection pointer, real report
+  rows, screenshots containing credentials, or temporary production IDs.
+- Never paste key contents into a terminal transcript, issue, or chat.
+
+## Restore the host app
+
+Restore the original configuration:
+
+```bash
+mv config/analytics_ops.yml "$analytics_smoke_backup/generated.yml"
+cp "$analytics_smoke_backup/original.yml" config/analytics_ops.yml
+cmp "$analytics_smoke_backup/original.yml" config/analytics_ops.yml
+```
+
+After confirming the restoration, remove the temporary backup with the
+operating system's normal secure cleanup process.
+
+Keep `~/.config/analytics_ops/connection.json`, the Cloud project, and the
+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,
+replace it with:
+
+```ruby
+gem "analytics_ops", "~> 0.2", group: :development
+```
+
+Run `bundle install`, then confirm `bundle info analytics_ops` resolves
+version `0.2.0` from RubyGems.
+
+## Release gate
+
+Do not tag while any live read-only command or local release check is failing.
+Require all of the following:
+
+- The complete live smoke test passed.
+- `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`.
+
+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
+```
+
+The tag workflow verifies and publishes through RubyGems Trusted Publishing.
+Never run a manual `gem push` or store a RubyGems API key.

data/docs/plan-format.md

@@ -63,6 +63,10 @@ before/after payloads, reversibility, and manual rollback guidance.
 Resource names in update payloads must belong to the plan's property. Immutable
 identity fields cannot change between `before` and `after`.
 
+Currency custom-metric payloads include `restricted_metric_types` with
+`cost_data`, `revenue_data`, or both. The classification is never inferred or
+changed automatically.
+
 ## Findings are not operations
 
 A finding may identify inaccessible resources, immutable conflicts, manual UI

data/docs/plan-schema-v1.json

@@ -53,8 +53,8 @@
             "resource_type": { "const": "data_stream" },
             "resource_identity": { "pattern": "^stream:[0-9]{1,50}$" },
             "operation": { "const": "update" },
-            "before": { "$ref": "#/$defs/dataStream" },
-            "after": { "$ref": "#/$defs/dataStream" }
+            "before": { "$ref": "#/$defs/dataStreamBefore" },
+            "after": { "$ref": "#/$defs/dataStreamAfter" }
           }
         },
         {
@@ -124,17 +124,38 @@
         "message": { "type": "string", "pattern": "^[^\\u0000-\\u001F\\u007F]{1,1000}$" }
       }
     },
-    "dataStream": {
+    "dataStreamBefore": {
       "type": "object",
       "additionalProperties": false,
       "required": ["id", "name", "display_name", "type", "default_uri", "measurement_id"],
       "properties": {
         "id": { "$ref": "#/$defs/id" },
         "name": { "$ref": "#/$defs/resourceName" },
-        "display_name": { "type": "string", "maxLength": 100 },
-        "type": { "enum": ["web", "android", "ios", "unspecified"] },
-        "default_uri": { "type": ["string", "null"], "format": "uri" },
-        "measurement_id": { "type": ["string", "null"], "maxLength": 64 }
+        "display_name": { "type": "string", "maxLength": 100, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
+        "type": { "const": "web" },
+        "default_uri": {
+          "type": ["string", "null"], "format": "uri", "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "measurement_id": {
+          "type": ["string", "null"], "maxLength": 64, "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        }
+      }
+    },
+    "dataStreamAfter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "display_name", "type", "default_uri", "measurement_id"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/resourceName" },
+        "display_name": { "type": "string", "maxLength": 100, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
+        "type": { "const": "web" },
+        "default_uri": {
+          "type": "string", "format": "uri", "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "measurement_id": {
+          "type": ["string", "null"], "maxLength": 64, "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        }
       }
     },
     "retention": {
@@ -144,13 +165,16 @@
       "properties": {
         "name": { "$ref": "#/$defs/resourceName" },
         "event_data": { "$ref": "#/$defs/retentionValue" },
-        "user_data": { "$ref": "#/$defs/retentionValue" },
+        "user_data": { "$ref": "#/$defs/userRetentionValue" },
         "reset_on_new_activity": { "type": "boolean" }
       }
     },
     "retentionValue": {
       "enum": ["2_months", "14_months", "26_months", "38_months", "50_months"]
     },
+    "userRetentionValue": {
+      "enum": ["2_months", "14_months"]
+    },
     "keyEvent": {
       "type": "object",
       "additionalProperties": false,
@@ -166,11 +190,28 @@
       "required": ["parameter_name", "display_name", "description", "scope", "disallow_ads_personalization"],
       "properties": {
         "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
-        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
-        "description": { "type": "string", "maxLength": 150 },
+        "display_name": {
+          "type": "string", "minLength": 1, "maxLength": 82,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "description": { "type": "string", "maxLength": 150, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
         "scope": { "enum": ["event", "user", "item"] },
         "disallow_ads_personalization": { "type": "boolean" }
-      }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "scope": { "const": "user" } } },
+          "then": {
+            "properties": {
+              "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,23}$" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "scope": { "enum": ["event", "item"] } } },
+          "then": { "properties": { "disallow_ads_personalization": { "const": false } } }
+        }
+      ]
     },
     "customDimensionUpdate": {
       "type": "object",
@@ -179,46 +220,96 @@
       "properties": {
         "name": { "$ref": "#/$defs/resourceName" },
         "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
-        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
-        "description": { "type": "string", "maxLength": 150 },
+        "display_name": {
+          "type": "string", "minLength": 1, "maxLength": 82,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "description": { "type": "string", "maxLength": 150, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
         "scope": { "enum": ["event", "user", "item"] },
         "disallow_ads_personalization": { "type": "boolean" }
-      }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "scope": { "const": "user" } } },
+          "then": {
+            "properties": {
+              "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,23}$" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "scope": { "enum": ["event", "item"] } } },
+          "then": { "properties": { "disallow_ads_personalization": { "const": false } } }
+        }
+      ]
     },
     "customMetricCreate": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["parameter_name", "display_name", "description", "scope", "measurement_unit"],
+      "required": [
+        "parameter_name", "display_name", "description", "scope", "measurement_unit", "restricted_metric_types"
+      ],
       "properties": {
         "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
-        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
-        "description": { "type": "string", "maxLength": 150 },
+        "display_name": {
+          "type": "string", "minLength": 1, "maxLength": 82,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "description": { "type": "string", "maxLength": 150, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
         "scope": { "const": "event" },
         "measurement_unit": {
           "enum": [
             "standard", "currency", "feet", "meters", "kilometers", "miles",
             "milliseconds", "seconds", "minutes", "hours"
           ]
+        },
+        "restricted_metric_types": {
+          "type": "array", "uniqueItems": true,
+          "items": { "enum": ["cost_data", "revenue_data"] }
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "measurement_unit": { "const": "currency" } } },
+          "then": { "properties": { "restricted_metric_types": { "minItems": 1 } } },
+          "else": { "properties": { "restricted_metric_types": { "maxItems": 0 } } }
+        }
+      ]
     },
     "customMetricUpdate": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "parameter_name", "display_name", "description", "scope", "measurement_unit"],
+      "required": [
+        "name", "parameter_name", "display_name", "description", "scope", "measurement_unit",
+        "restricted_metric_types"
+      ],
       "properties": {
         "name": { "$ref": "#/$defs/resourceName" },
         "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
-        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
-        "description": { "type": "string", "maxLength": 150 },
+        "display_name": {
+          "type": "string", "minLength": 1, "maxLength": 82,
+          "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+        },
+        "description": { "type": "string", "maxLength": 150, "pattern": "^[^\\u0000-\\u001F\\u007F]*$" },
         "scope": { "const": "event" },
         "measurement_unit": {
           "enum": [
             "standard", "currency", "feet", "meters", "kilometers", "miles",
             "milliseconds", "seconds", "minutes", "hours"
           ]
+        },
+        "restricted_metric_types": {
+          "type": "array", "uniqueItems": true,
+          "items": { "enum": ["cost_data", "revenue_data"] }
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "measurement_unit": { "const": "currency" } } },
+          "then": { "properties": { "restricted_metric_types": { "minItems": 1 } } },
+          "else": { "properties": { "restricted_metric_types": { "maxItems": 0 } } }
+        }
+      ]
     }
   }
 }

data/docs/rails.md

@@ -14,6 +14,9 @@ Active Support.
 
 ```bash
 bundle install
+bundle exec analytics-ops setup \
+  --profile development \
+  --service-account /absolute/path/to/service-account.json
 bin/rails generate analytics_ops:install
 ```
 
@@ -22,14 +25,20 @@ The generator creates only:
 - `config/analytics_ops.yml`
 - `bin/analytics-ops` with executable mode
 
-The generated file has a `development` profile and fake-safe placeholders.
-Add a profile matching the Rails environment you intend to operate, or set
-`ANALYTICS_OPS_PROFILE`.
+If setup already created the configuration, the generator preserves it and
+adds only the binstub. It never asks to overwrite the selected property.
+
+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`.
 
 ## Rake tasks
 
 ```bash
 bin/rake analytics:doctor
+bin/rake analytics:overview
 bin/rake analytics:audit
 bin/rake analytics:plan
 bin/rake analytics:verify

data/docs/reports.md

@@ -17,7 +17,11 @@ All standard recipes cover the previous 28 complete days
 | `shares_and_prints` | Share and print events by calculator | `customEvent:calculator_slug` |
 | `related_calculator_navigation` | Related-calculator clicks by source and destination | `customEvent:calculator_slug`, `customEvent:related_calculator_slug` |
 | `commercial_outbound_clicks` | Commercial outbound clicks by calculator and destination | `customEvent:calculator_slug`, `customEvent:outbound_destination` |
-| `realtime_events` | Event count and active users by event name | None |
+| `realtime_events` | Event count by event name | None |
+
+The CLI also accepts `traffic` as an alias for `traffic_acquisition` and
+`landing-pages` as an alias for `landing_pages`. Canonical names remain in
+JSON and Ruby results.
 
 The event names used by the calculator recipes are
 `calculation_completed`, `result_shared`, `result_printed`,
@@ -27,15 +31,39 @@ If your site uses different names, create a custom Ruby definition.
 ## CLI
 
 ```bash
-analytics-ops report traffic_acquisition
-analytics-ops report landing_pages --format json
-analytics-ops report calculator_completions --format csv
+analytics-ops overview
+analytics-ops report traffic
+analytics-ops report landing-pages --json
+analytics-ops report calculator_completions --csv
 analytics-ops realtime
 ```
 
 CSV is accepted only for `report` and `realtime`. The CSV renderer protects
-cells that start with `=`, `+`, `-`, or `@` from spreadsheet formula
-execution.
+headers and cells whose first meaningful character is `=`, `+`, `-`, or `@`,
+including formula text hidden behind whitespace or control characters.
+
+## Overview
+
+`analytics-ops overview` uses one `batchRunReports` call containing five
+small reports for the previous 28 complete days:
+
+- totals for active users, sessions, and key events
+- a daily trend
+- traffic acquisition
+- landing pages
+- device categories
+
+Each subreport has a small row limit, and Google property-quota information is
+preserved when returned. Batching reduces network round trips; it does not
+make the underlying report work quota-free. CSV is intentionally unavailable
+for this multi-report result. Use `--json` for structured overview output.
+
+The dimensionless totals request keeps empty rows so a brand-new property
+still returns the expected metric headers.
+
+The realtime recipe intentionally requests only `eventCount` with
+`eventName`. Google does not allow `activeUsers` with that dimension. Realtime
+is a short-lived event check rather than a complete user report.
 
 ## Ruby
 
@@ -49,6 +77,10 @@ result = workspace.report("traffic_acquisition")
 puts result.headers
 puts result.rows
 puts result.metadata
+
+overview = workspace.overview
+puts overview.report("overview_totals").rows
+puts overview.property_quota
 ```
 
 Custom immutable definition:
@@ -82,6 +114,12 @@ metrics, invalid date order, filters that reference unselected fields,
 non-finite numeric filters, invalid ordering, and unbounded limits. Realtime
 definitions cannot use date ranges or offsets.
 
+Dates use only `YYYY-MM-DD`, `NdaysAgo`, `yesterday`, or `today`. Absolute and
+relative ranges are checked for reversed endpoints. A request may contain up
+to four uniquely named ranges; comparison responses include Google's
+automatic `dateRange` dimension. Numeric filters accept only finite doubles or
+signed 64-bit integers.
+
 ## Result shape
 
 `result.to_h` contains:

data/docs/safety.md

@@ -4,9 +4,12 @@ Analytics Ops is read-only unless you explicitly apply a saved plan.
 
 ## What cannot mutate
 
-`doctor`, `discover`, `snapshot`, `audit`, `plan`, `verify`,
-`report`, and `realtime` only read Google APIs. Loading the gem, parsing
-YAML, and booting Rails make no network request.
+`properties`, `doctor`, `discover`, `snapshot`, `audit`, `plan`, `verify`,
+`overview`, `report`, and `realtime` only read Google Analytics APIs. Setup
+validates a service-account key, verifies access, remembers only its path, and
+creates local configuration; it never changes Analytics. Loading the gem,
+constructing a connection, parsing YAML, and booting Rails make no network
+request.
 
 ## What apply requires
 
@@ -20,6 +23,9 @@ An apply needs all of these:
 The applier executes only the operations stored in the file. It never replans
 during apply and never turns findings into changes.
 
+The Ruby API also requires the literal boolean `true`; truthy strings or
+objects do not count as confirmation.
+
 ## Stale plans
 
 Every plan fingerprints normalized managed remote state with SHA-256. If that
@@ -74,7 +80,7 @@ with mode 0600. Loading rejects:
 - unknown resource payload fields
 - unsupported operations
 - no-op updates and immutable-field changes
-- secret-shaped fields and control characters
+- secret-shaped fields, credential-shaped text, and control characters
 - resource names for another property
 
 Workspace and adapter checks provide additional cross-property protection.
@@ -83,11 +89,17 @@ The public schema is [plan-schema-v1.json](plan-schema-v1.json).
 ## Credential and data boundaries
 
 - Credentials never belong in YAML, plans, fixtures, logs, or command output.
+- `~/.config/analytics_ops/connection.json` contains only a key path, is
+  atomic, and uses mode `0600`; the key is never copied.
+- Ambient Application Default Credentials and API keys are never used.
+- Read-only commands request only `analytics.readonly`; guarded apply also
+  requests `analytics.edit`.
 - Report rows are never logged automatically.
 - The gem has no telemetry and stores no report results.
 - The gem does not inject browser analytics or manage consent.
 - Production mutation credentials should not exist in a Rails web container.
 - Real production IDs and exports do not belong in repository fixtures.
 
-Use a read-only identity for routine audits and reports. Use a separately
-protected edit identity only for a reviewed apply.
+Use a Viewer service account for reports-only installations. If one service
+account has the Editor role, Analytics Ops still requests edit scope only
+inside the reviewed apply path.

data/docs/troubleshooting.md

@@ -3,10 +3,13 @@
 Start with:
 
 ```bash
-analytics-ops doctor --format json
+analytics-ops setup --service-account /absolute/path/to/service-account.json
+analytics-ops properties
+analytics-ops doctor --json
 ```
 
-The command is read-only and checks both Google APIs.
+`properties` works without configuration. Setup verifies both APIs and creates
+the minimal file; doctor performs the complete configured-property check.
 
 ## Configuration error
 
@@ -23,28 +26,51 @@ stream_id: "987654321"
 
 Do not use account ID `100000001` or measurement ID `G-EXAMPLE1` in those
 fields. Unknown keys, ERB, YAML aliases, missing environment variables, and
-secret-shaped fields are intentionally rejected.
+secret- or credential-shaped material are intentionally rejected.
+
+Currency custom metrics require an explicit restricted-data classification:
+
+```yaml
+measurement_unit: currency
+restricted_metric_types: [revenue_data]
+```
+
+Use `cost_data`, `revenue_data`, or both according to the metric's meaning.
+Analytics Ops will not guess. User-data retention accepts only `2_months` or
+`14_months`; longer 360 periods apply only to event data.
 
 ## Authentication failure (exit 66)
 
-Create ADC again and ensure both APIs are enabled:
+Analytics Ops could not load or use the configured service account.
 
 ```bash
-gcloud auth application-default login \
-  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
+analytics-ops setup \
+  --service-account /absolute/path/outside/repositories/service-account.json
 ```
 
-If `GOOGLE_APPLICATION_CREDENTIALS` is set, confirm that it points to the
-intended local credential file. Never add that path or file to configuration
-or source control.
+Check that:
+
+- the file still exists at that path
+- it is a JSON key whose `type` is `service_account`
+- the key has not been revoked in Google Cloud
+- the Analytics Admin and Data APIs are enabled in its Cloud project
+- the service-account email is added in GA4 Access Management
+
+The saved pointer is `~/.config/analytics_ops/connection.json`. It contains
+only the key path. Rerunning setup with `--service-account` safely replaces
+that pointer after API verification succeeds.
+
+Analytics Ops does not fall back to `gcloud`, browser login, Application
+Default Credentials, `GOOGLE_APPLICATION_CREDENTIALS`, or API keys.
 
 ## Permission failure (exit 77)
 
-The Google identity needs access inside the GA4 property. Cloud IAM alone is
-not enough. Add the user or service-account identity to the property with a
-read role; use an edit-capable role only for plan application.
+The service-account identity needs access inside the GA4 property. Cloud IAM
+alone is not enough. Add its email to GA4 Access Management with Viewer for
+reads or Editor for plan application.
 
-Use `analytics-ops discover` to see accessible numeric property IDs.
+Use `analytics-ops properties` to see accessible numeric property IDs without
+creating configuration. `discover` additionally retrieves streams.
 
 ## API or remote failure (exit 69)
 
@@ -53,6 +79,9 @@ credential's Cloud project. Check the configuration ID and the error's typed
 message. Invalid dimensions, metrics, custom definitions, or property
 restrictions can also produce this status.
 
+When setup recognizes disabled APIs, enable both APIs in the Google Cloud
+project that owns the service account.
+
 ## Quota (exit 75) or timeout (exit 74)
 
 Wait for Google quota to recover, reduce report frequency, or use a positive

data/lib/analytics_ops/applier.rb

@@ -15,7 +15,8 @@ module AnalyticsOps
     end
 
     def call(plan, confirm: false)
-      raise ConfirmationRequiredError, "Applying a plan requires explicit confirmation" unless confirm
+      raise ConfirmationRequiredError, "Applying a plan requires explicit boolean confirmation" unless confirm == true
+      raise InvalidPlanError, "plan must be an AnalyticsOps::Plan" unless plan.is_a?(Plan)
 
       current = @admin.snapshot(plan.property_id)
       unless current.fingerprint == plan.snapshot_fingerprint