analytics_ops 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf17db3adc805f77cf7d22e2ea2840a3eaf44a007be8036a48bf58a4d2d3a36
-  data.tar.gz: 1642e17fb59a976a471636a92f8da2f1290c3e13eb7bee515722efd8315a2e4a
+  metadata.gz: f71655d305efa516ee61d1d1059078f6e0bd562949a542e764dceff69eb58017
+  data.tar.gz: d73a4e6cb8aa1de4ec019104bcc28ab259be236dd41612f73be4124a0f4bae56
 SHA512:
-  metadata.gz: c934c5e8856505c2ec5d8e4311ac9f9e3d23ba47078fc478170dcda4d08e5d5be990402fa2795d56138ba30d2c8e92dbe368fdb1fb3da254bead9ba429338f09
-  data.tar.gz: b96a8112f501416f763d3528419435e2364526f66cd43266ec3880825f61c964550eca739ece89607d7d89a583051b44d35d1f3f62a018260dab625d13a871ef
+  metadata.gz: ff58c5f35e8573755d4dab309163602124fda905aa2e452568e04ceef4d12d8b370e2d573b7783ab150b6083c2657dbf9cf03e6c4124ca8931cfe4ef01966679
+  data.tar.gz: 5495494e5cae8ba1a786644752038a5749cf4aa2cdb05cbfc12da0923c8558596be1391b3f1806cf7739ea6ad13ea57a01150ff0e69e2f4e57a86232ab14df86

data/CHANGELOG.md

@@ -3,6 +3,82 @@
 Analytics Ops follows Semantic Versioning for its public Ruby, CLI,
 configuration, and plan contracts.
 
+## [0.2.0] - 2026-07-22
+
+### Added
+
+- Configuration-free `properties` and `discover` commands, removing the
+  property-ID onboarding deadlock.
+- Service-account-only `setup` with strict JSON-key validation, numbered
+  property selection, effective API access checks, and non-interactive
+  automation support.
+- Atomic mode-`0600` user-level connection storage that remembers only the
+  service-account key path and never copies the key.
+- Non-destructive atomic creation of the smallest valid `production`
+  configuration. Matching configuration is reused; conflicting profiles are
+  never overwritten.
+- A five-section, row-bounded `overview` powered by one official
+  `batchRunReports` request, with immutable normalized results and property
+  quota metadata.
+- Friendly `traffic` and `landing-pages` report aliases plus `--json` and
+  `--csv` format shortcuts.
+- Optional Rails `analytics:overview` Rake task.
+- A public real-app read-only smoke-test and release-gate guide using the
+  single service-account authentication path.
+
+### Changed
+
+- Account/property-only discovery no longer fetches every property's streams;
+  detailed `discover` retains the original stream output.
+- The setup, connection, overview, CLI, Google-client, RBS, and operator
+  documentation now describe the simpler three-command start.
+- Currency custom metrics now carry Google's required cost/revenue restricted-
+  data classification through configuration, snapshots, plans, and requests.
+- Rails installation now generates a minimal property-only configuration, so
+  sample stream or retention values cannot become accidental changes.
+- The Rails generator preserves configuration already created by setup and
+  adds the binstub without an overwrite prompt.
+- Every CLI and Ruby orchestration path now loads an explicit service account;
+  ambient credentials, API keys, browser login, and external CLI
+  authentication are not fallback paths.
+- `googleauth` is now a direct reviewed dependency because Analytics Ops calls
+  its service-account loader explicitly.
+- Read-only operations request only `analytics.readonly`; guarded apply
+  creates a separate client with `analytics.edit`.
+
+### Fixed
+
+- Keep empty rows for dimensionless standard reports so overview totals retain
+  their metric headers on a new or empty GA4 property.
+- Use only Google's compatible `eventCount` metric in the built-in
+  `realtime_events` recipe.
+- Reject duplicate or excessively nested YAML, impossible user-retention
+  periods, Google-invalid custom-definition display names, oversized stream
+  URIs, reversed report dates, malformed numeric filters, and non-finite
+  client options before calling Google.
+- Preserve Google's automatic `dateRange` column, distinguish absent report
+  metadata, validate quota/row/header shapes, and reject invalid UTF-8 output.
+- Translate pagination and raw socket failures into typed errors and reject
+  malformed or cross-property Admin responses.
+- Require the literal boolean `true` for Ruby apply confirmation and reject
+  non-web, cross-property, or otherwise forged saved-plan payloads.
+- Handle Ctrl-C as clean human or JSON output with exit status 130 instead of
+  dumping a Ruby backtrace.
+
+### Security
+
+- Setup validates a bounded service-account key and stores only its canonical
+  path outside the project; keys never enter configuration, plans, logs, or
+  output.
+- Setup verifies access before writing configuration or remembering the key
+  path, and non-interactive mode never prompts.
+- Credential-shaped values are rejected from configuration and plans; JSON
+  secret assignments, invalid bytes, and terminal controls are sanitized.
+- Human output is terminal-safe, and CSV formula protection covers headers and
+  values hidden behind whitespace or controls.
+- Existing guarded apply, stale-plan, no-delete, redaction, and no-network-on-
+  load guarantees remain unchanged.
+
 ## [0.1.0] - 2026-07-22
 
 ### Added

data/CONTRIBUTING.md

@@ -26,7 +26,8 @@ mounted read-only except for source edits.
 ## Design rules
 
 - Keep the core plain Ruby and independent of Rails and Active Support.
-- Use Google's official Ruby clients; do not add another HTTP or OAuth stack.
+- Use Google's official Ruby clients and the service-account-only contract; do
+  not add another HTTP or authentication stack.
 - Keep generated Google objects behind adapters.
 - Do not introduce telemetry, a database, browser analytics, or boot-time
   network access.

data/README.md

@@ -6,51 +6,226 @@ Analytics Ops gives you a review-first way to inspect GA4, detect drift, run
 useful reports, and apply a small set of safe configuration changes. The core
 is plain Ruby; Rails support is optional.
 
-## Five-minute read-only start
+## Three-command start
 
-You need Ruby 3.2 or newer, a GA4 property you can read, and the
-[Google Cloud CLI](https://cloud.google.com/sdk/docs/install).
+You need Ruby 3.2 or newer, access to a GA4 property, and a Google
+service-account JSON key kept outside the repository.
 
-1. Add Analytics Ops to your bundle:
+```bash
+gem install analytics_ops
+analytics-ops setup --service-account /absolute/path/to/service-account.json
+analytics-ops overview
+```
+
+`setup` lists the properties the service account can access, lets you choose
+one, and creates the smallest valid `config/analytics_ops.yml` for the default
+`production` profile. It securely remembers the key's path, so every later
+command works without another authentication option. You do not need
+`gcloud`, browser authorization, a property ID, or hand-written YAML.
+
+`overview` makes one bounded batch request and shows totals, a daily trend,
+traffic acquisition, landing pages, and devices for the previous 28 complete
+days. Both commands are read-only in Google Analytics.
+
+## Google Analytics setup (first time only)
+
+The setup is easier when you keep these four separate things in mind:
+
+| Item | What it does |
+| --- | --- |
+| Human Google Account | The account you use to sign in to Google Analytics and Google Cloud |
+| GA4 account and property | Holds your website's analytics configuration and collected data |
+| Google Cloud project | Owns API access, quota, and the service account; it does not hold your GA4 report data |
+| Service account | The non-human identity Analytics Ops uses to call Google's APIs |
+
+### A. Create GA4 only if you do not already have it
+
+Already have a working GA4 property collecting website data? Skip to
+[Create the Google Cloud project](#b-create-the-google-cloud-project).
+
+1. Sign in at [Google Analytics](https://analytics.google.com).
+2. Click **Start Measuring**, or open **Admin → Create → Account**.
+3. Create an Analytics account.
+4. Create a GA4 property and choose its reporting time zone and currency.
+5. Create a Web data stream using your website URL.
+6. Install the resulting Google tag or Measurement ID on your website.
+
+Analytics Ops reads and manages an existing GA4 property. It does not install
+the website tracking tag or send browser events.
+
+### B. Create the Google Cloud project
+
+1. Sign in at [Google Cloud](https://console.cloud.google.com).
+2. Open the project selector and choose **New Project**.
+3. Use a clear name such as **Analytics Ops**.
+4. Choose **No organization** if you use a personal account. That is fine.
+5. Create the project and make sure it is selected before continuing.
+
+Google requires this separate project for API access, quota, and the service
+account identity. Creating it does not create another GA4 account or move your
+analytics data.
+
+### C. Enable the two required APIs
+
+In the selected Cloud project, open **APIs & Services → Library** and enable
+exactly:
+
+- **Google Analytics Admin API**
+- **Google Analytics Data API**
+
+You do not need the Gemini API.
+
+### D. Create the service account
+
+1. Open **IAM & Admin → Service Accounts**.
+2. Click **Create service account**.
+3. Use a name such as **Analytics Ops Local**.
+4. Continue past the optional Cloud permissions step without assigning
+   **Owner**, **Editor**, or another broad Cloud IAM role.
+5. Finish creating the service account.
+6. Copy its email address. It resembles:
+   `analytics-ops@example-project.iam.gserviceaccount.com`.
+
+Google Cloud IAM Editor and GA4 Editor are different roles. The service
+account does not need the Cloud IAM Editor role.
+
+### E. Download and protect the JSON key
+
+1. Open the service account you just created.
+2. Open **Keys**.
+3. Choose **Add key → Create new key → JSON**.
+4. Download the key.
+5. Move it to a stable location outside every application repository.
+6. On macOS or Linux, protect it with mode `0600`:
+
+```bash
+mkdir -p ~/.config/analytics_ops
+chmod 700 ~/.config/analytics_ops
+mv /path/to/downloaded-key.json \
+  ~/.config/analytics_ops/service-account.json
+chmod 600 ~/.config/analytics_ops/service-account.json
+```
+
+Protect this file like a password:
 
-   ```ruby
-   # Gemfile
-   gem "analytics_ops", "~> 0.1", group: :development
-   ```
+- Never commit it.
+- Never paste its contents into chat, logs, screenshots, issues, or
+  environment variables.
+- Do not put it inside `config/analytics_ops.yml`.
+- If it is exposed, revoke the key in Google Cloud and create a replacement.
 
-   ```bash
-   bundle install
-   ```
+### F. Give the service account GA4 access
 
-2. Enable the Google Analytics Admin API and Data API in your own Google Cloud
-   project, then create local Application Default Credentials:
+1. Return to [Google Analytics](https://analytics.google.com).
+2. Select the correct GA4 account and property.
+3. Open **Admin**.
+4. Choose **Property access management** for one property, or **Account access
+   management** for every property in that GA4 account.
+5. Click **+ → Add users**.
+6. Paste the service-account email.
+7. Disable **Notify new users by email**. A service account has no human
+   inbox.
+8. Select **Viewer** for reports, discovery, snapshots, doctor, and audit.
+   Select **Editor** only if you plan to use reviewed `apply` operations
+   later.
+9. Do not grant **Administrator**. Analytics Ops does not manage GA4 users.
+10. Click **Add**.
 
-   ```bash
-   gcloud auth application-default login \
-     --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
-   ```
+Your human Google Account must already have permission to manage users in
+that GA4 account or property.
 
-3. Create `config/analytics_ops.yml`:
+### G. Install and connect Analytics Ops
 
-   ```yaml
-   version: 1
+For a standalone installation:
 
-   profiles:
-     production:
-       property_id: "123456789"
-   ```
+```bash
+gem install analytics_ops
+analytics-ops setup \
+  --service-account ~/.config/analytics_ops/service-account.json
+```
+
+For an application that uses Bundler, add:
+
+```ruby
+# Gemfile
+gem "analytics_ops", "~> 0.2", group: :development
+```
+
+Then run:
+
+```bash
+bundle install
+bundle exec analytics-ops setup \
+  --service-account ~/.config/analytics_ops/service-account.json
+```
+
+Setup:
+
+- validates the key
+- verifies both Analytics APIs
+- lists the GA4 properties the service account can access
+- lets you choose a property
+- creates `config/analytics_ops.yml`
+- remembers only the key's absolute path in
+  `~/.config/analytics_ops/connection.json`
+
+### H. Verify the connection with read-only commands
 
-4. Check access without changing anything:
+```bash
+bundle exec analytics-ops doctor
+bundle exec analytics-ops properties
+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 normal for a new property. These checks are read-only in
+GA4. Setup also makes no GA4 changes; it writes only the local configuration
+and connection pointer.
+
+`audit` exits with status `0` when configuration matches and status `2` when
+it finds drift. Both are successful read-only results.
+
+You do not need `gcloud`, a browser OAuth login, an OAuth consent screen, an
+OAuth test-user list, or Gemini. An API key cannot authorize access to private
+GA4 data.
+
+`apply` is the mutating command. Do not run it until you have created and
+reviewed a saved plan.
+
+### I. Quick troubleshooting
 
-   ```bash
-   bundle exec analytics-ops doctor
-   bundle exec analytics-ops discover
-   bundle exec analytics-ops audit
-   bundle exec analytics-ops report traffic_acquisition
-   ```
+- **No properties listed:** Add the exact service-account email to the correct
+  GA4 account or property.
+- **API disabled:** Select the correct Cloud project and confirm both
+  Analytics APIs are enabled.
+- **Permission denied:** Grant Viewer or Editor inside GA4. A Google Cloud IAM
+  role does not grant access to GA4 data.
+- **“This app is blocked” opens in a browser:** That is an obsolete OAuth
+  flow. Analytics Ops 0.2 uses a service-account JSON key and does not launch
+  browser authorization.
+- **Key unavailable:** Run setup again with the key's new absolute path.
+- **Key creation disabled:** An organization policy may prohibit downloaded
+  service-account keys. Ask the Google Workspace or Cloud administrator.
 
-Every command above is read-only. `audit` exits with status 2 when it finds
-drift, which makes it useful in CI.
+Google's official guides cover
+[GA4 account and property creation](https://support.google.com/analytics/answer/14183469?hl=en),
+[Cloud project creation](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects),
+[API enablement](https://docs.cloud.google.com/service-usage/docs/enable-disable),
+[service-account creation](https://docs.cloud.google.com/iam/docs/service-accounts-create),
+[JSON key creation](https://docs.cloud.google.com/iam/docs/keys-create-delete),
+and [GA4 access management](https://support.google.com/analytics/answer/9305788?hl=en).
+
+See the [live read-only smoke-test guide](docs/live-smoke-test.md) for a safe
+real-app release test.
+
+Already connected? List properties before creating configuration:
+
+```bash
+analytics-ops properties
+analytics-ops discover # includes data streams
+```
 
 ## The safe change workflow
 
@@ -81,8 +256,11 @@ what failed, and what remains.
 
 | Command | Purpose | Remote writes? |
 | --- | --- | --- |
+| `analytics-ops setup --service-account PATH` | Connect, choose a property, and create minimal configuration | No |
+| `analytics-ops properties` | List accessible accounts and properties without configuration | No |
 | `analytics-ops doctor` | Check configuration, credentials, APIs, property access, clients, and clock | No |
-| `analytics-ops discover` | List accessible accounts, properties, and streams | No |
+| `analytics-ops discover` | List accessible accounts, properties, and streams without configuration | No |
+| `analytics-ops overview` | Show five useful reports in one bounded batch | No |
 | `analytics-ops snapshot` | Print normalized managed remote state | No |
 | `analytics-ops audit` | Show drift without writing a plan file | No |
 | `analytics-ops plan --output FILE` | Review and save deterministic changes | No |
@@ -92,12 +270,16 @@ what failed, and what remains.
 | `analytics-ops realtime` | Run the realtime-events report | No |
 | `analytics-ops schema --format json` | Print the configuration schema | No |
 
-Use `--format json` for automation. CSV is available only for reports:
+Use `--json` or `--format json` for automation. CSV is available only for
+individual reports:
 
 ```bash
-bundle exec analytics-ops report landing_pages --format csv
+bundle exec analytics-ops report landing-pages --csv
 ```
 
+Friendly `traffic` and `landing-pages` aliases leave the original
+`traffic_acquisition` and `landing_pages` names fully supported.
+
 See [Commands](docs/commands.md) for every option and exit status.
 
 ## IDs: the quick distinction
@@ -110,8 +292,8 @@ Use fake values like these in examples and tests:
 | Property ID | `123456789` | `property_id` in configuration and API requests |
 | Stream ID | `987654321` | `stream_id` in configuration |
 | Measurement ID | `G-EXAMPLE1` | Browser tagging; never use it as a stream ID |
-| OAuth client | A Cloud project client ID/secret | Owned by your application, never this YAML |
-| Service-account identity | `ga-reader@example-project.iam.gserviceaccount.com` | Granted GA access; its key is never this YAML |
+| Cloud project | `example-analytics-project` | Owns enabled APIs, quota, and the service account |
+| Service-account identity | `ga-reader@example-project.iam.gserviceaccount.com` | Granted GA4 access; its key is never this YAML |
 
 ## Ruby API
 
@@ -126,6 +308,9 @@ plan.write("tmp/ga4-plan.json")
 
 report = workspace.report("calculator_completions")
 report.rows.each { |row| puts row.fetch("eventCount") }
+
+overview = workspace.overview
+puts overview.report("overview_totals").rows
 ```
 
 Loading the gem, loading YAML, and booting Rails do not contact Google.
@@ -139,8 +324,12 @@ gem "analytics_ops", require: "analytics_ops/rails", group: :development
 ```
 
 ```bash
+bundle exec analytics-ops setup \
+  --profile development \
+  --service-account /absolute/path/to/service-account.json
 bin/rails generate analytics_ops:install
 bin/rake analytics:doctor
+bin/rake analytics:overview
 bin/rake 'analytics:report[traffic_acquisition]'
 ```
 
@@ -151,17 +340,19 @@ boot-time network calls. See [Rails integration](docs/rails.md).
 ## What Analytics Ops does not do
 
 - It does not inject browser analytics or manage consent banners.
-- It does not store credentials, tokens, report rows, or local state.
+- It stores only the service-account key's path in a mode-`0600` user file;
+  it never copies the key, tokens, or report rows.
 - It does not delete accounts, properties, streams, or unmanaged resources.
 - It does not claim to manage settings that Google exposes only in the UI.
-- Experimental declarations are findings only in version 0.1.0; they are not
+- Experimental declarations are findings only in version 0.2.0; they are not
   silently applied through Alpha APIs.
 
 ## Documentation
 
 | Guide | Topic |
 | --- | --- |
-| [Authentication](docs/authentication.md) | ADC, scopes, service accounts, and safe automation |
+| [Authentication](docs/authentication.md) | One-time service-account setup and key safety |
+| [Live smoke test](docs/live-smoke-test.md) | Real-app read-only verification and release gate |
 | [Configuration](docs/configuration.md) | Complete strict YAML contract |
 | [Commands](docs/commands.md) | CLI syntax, formats, and exit statuses |
 | [Reports](docs/reports.md) | Built-in recipes and GA reporting limitations |

data/SECURITY.md

@@ -29,18 +29,18 @@ do not wait for a project response.
 
 Analytics Ops:
 
-- uses Application Default Credentials or an explicitly injected Google
-  credential object
-- refuses credential-shaped configuration and plan fields
+- uses only an explicit Google service-account key and never discovers
+  ambient credentials
+- refuses credential-shaped configuration and plan fields or values
 - redacts common authorization material from translated errors
 - performs no network I/O while requiring the gem, loading YAML, or booting
   Rails
 - defaults to read-only commands
-- requires a strictly validated saved plan and explicit confirmation to mutate
+- requires a strictly validated saved plan and literal boolean confirmation to mutate
 - rejects stale and cross-property plans
 - excludes delete/archive operations from ordinary plans
 - never logs report results automatically
-- has no telemetry, credential store, database, or browser injection
+- has no telemetry, private-key/token store, database, or browser injection
 - publishes through RubyGems Trusted Publishing without a stored API key
 
 Plan files still describe operational configuration and are created with mode
@@ -51,6 +51,6 @@ under the operator's data policy.
 
 Analytics Ops cannot secure an overprivileged Cloud project, service account,
 GitHub organization, CI runner, GA property, or exported report. Use
-least-privilege read credentials for routine work, isolate mutation
-credentials, protect release environments, and keep production mutation
-credentials out of Rails web containers.
+Viewer access when an installation only reports or audits; grant Editor only
+when reviewed applies are required. Protect release environments and keep
+production mutation credentials out of Rails web containers.

data/docs/api-support-matrix.md

@@ -1,6 +1,6 @@
 # API support matrix
 
-This matrix describes Analytics Ops 0.1.0—not every method Google exposes.
+This matrix describes Analytics Ops 0.2.0—not every method Google exposes.
 
 | State | Meaning |
 | --- | --- |
@@ -10,27 +10,28 @@ This matrix describes Analytics Ops 0.1.0—not every method Google exposes.
 | Manual | Reported as an operator checklist |
 | Unsupported | Deliberately outside the public contract |
 
-| Capability | State | Exact 0.1.0 behavior |
+| Capability | State | Exact 0.2.0 behavior |
 | --- | --- | --- |
-| Account/property discovery | Audited | Lists accessible summaries |
-| Data-stream discovery | Audited | Lists web, Android, and iOS streams |
+| Account/property discovery | Audited | Lists accessible summaries without requiring configuration |
+| Data-stream discovery | Audited | Lists web, Android, and iOS streams without requiring configuration |
 | Web stream default URI | Managed | Updates an existing web stream |
 | Stream create/delete | Unsupported | Missing streams become findings |
 | Data retention | Managed | Reads and updates supported periods/reset behavior |
 | Key events | Managed | Reads and creates missing events; no delete |
 | Custom dimensions | Managed | Reads, creates, and updates display name/description; user ads flag where supported |
-| Custom metrics | Managed | Reads, creates, and updates display name/description |
+| Custom metrics | Managed | Reads and creates with explicit currency-data classification; updates display name/description |
 | Standard Data API reports | Audited | Immutable definitions and normalized results |
 | Realtime Data API reports | Audited | Immutable definitions and normalized results |
-| Batch reports | Unsupported | Use individual definitions |
+| Batched overview | Audited | Five bounded standard reports through one `batchRunReports` call |
+| Friendly report aliases | Audited | `traffic` and `landing-pages` resolve to stable canonical recipes |
 | Enhanced Measurement | Experimental | Validated declaration and finding only; no mutation |
 | Google Signals | Experimental | Validated declaration and finding only; no mutation |
 | Consent coverage | Manual | Must be verified in tagging/consent systems |
 | Ads-personalization regions | Manual | Not inferred from similarly named API fields |
 | Stream data redaction | Manual | UI/API policy must be verified separately |
 | User-provided data setting | Unsupported | Not read or changed |
-| Event create/edit rules | Unsupported | Alpha, outside 0.1.0 |
-| Audiences and expanded datasets | Unsupported | Alpha, outside 0.1.0 |
+| Event create/edit rules | Unsupported | Alpha, outside 0.2.0 |
+| Audiences and expanded datasets | Unsupported | Alpha, outside 0.2.0 |
 | Google Ads, AdSense, DV360, SA360 links | Unsupported | Not read or changed |
 | BigQuery links | Unsupported | Not read or changed |
 | Access bindings | Unsupported | Not read or changed |

data/docs/architecture.md

@@ -15,6 +15,12 @@ strict YAML
 immutable report definition
   → Data API adapter
   → immutable normalized result
+
+configuration-free connection
+  → explicit service-account identity
+  → account/property discovery
+  → API access verification
+  → atomic minimal configuration
 ```
 
 ## Core objects
@@ -22,6 +28,7 @@ immutable report definition
 | Object | Responsibility |
 | --- | --- |
 | `Configuration` | Bounded safe YAML, environment interpolation, schema validation |
+| `Configuration::Writer` | Non-destructive atomic creation of the smallest valid setup file |
 | `DesiredState` | Immutable configuration for one profile |
 | `Resources` | Gem-owned account/property/stream/settings values |
 | `Snapshot` | Canonical managed remote state and SHA-256 fingerprint |
@@ -31,6 +38,9 @@ immutable report definition
 | `Clients::Admin` | Official Admin request translation and response normalization |
 | `Reports::Definition` | Strict immutable Data API query |
 | `Clients::Data` | Standard/realtime request translation and result normalization |
+| `ServiceAccount` | Strict JSON-key validation, scopes, and user-level path storage |
+| `Connection` | Configuration-free discovery and selected-property access verification |
+| `Setup` | Property selection, verification, and safe configuration creation |
 | `Workspace` | Public orchestration API with independently injectable clients |
 | `CLI` | Option validation, formats, stable statuses, and explicit confirmation |
 | `Railtie` | Optional generator and operator Rake tasks |
@@ -38,12 +48,14 @@ immutable report definition
 ## Dependency direction
 
 Domain and planning code know nothing about protobufs, gRPC, Rails, Active
-Support, OAuth flows, or HTTP transports. Admin and Data adapters translate
+Support, authentication flows, or HTTP transports. Admin and Data adapters translate
 official generated values immediately into immutable Analytics Ops values.
 The adapters can be injected independently, so tests use deterministic fakes.
 
-The core requires Google's wrapper gems lazily. Requiring `analytics_ops`
-defines classes only; it does not instantiate a client or discover ADC.
+The core requires Google's wrapper gems lazily. Requiring `analytics_ops`,
+constructing a `Connection`, loading configuration, and booting Rails define
+or validate local objects only; they do not instantiate a generated client,
+read a service-account key, or contact Google.
 
 ## State model
 
@@ -52,6 +64,12 @@ database. The configuration declares desired state and a snapshot captures the
 relevant remote state. Canonical key ordering and normalized arrays make
 snapshot fingerprints and plan bytes deterministic.
 
+`setup` discovers properties through a configuration-free `Connection`,
+verifies the selected property, and creates the existing versioned YAML
+format. Existing conflicting configuration is never rewritten. A separate
+user-level `connection.json` stores only the absolute service-account key
+path. It is not desired state and contains no key material.
+
 Apply accepts an already validated plan, refreshes the snapshot, compares its
 fingerprint, then sends only the saved operations. A partial response is
 explicit reconciliation data, not a hidden retry or rollback.
@@ -83,7 +101,7 @@ call. Browser analytics and consent remain application concerns.
 
 ## Experimental boundary
 
-Google identifies certain Admin capabilities as Alpha. Version 0.1.0 accepts
+Google identifies certain Admin capabilities as Alpha. Version 0.2.0 accepts
 explicit Enhanced Measurement and Google Signals declarations only so they can
 appear as experimental findings. It does not apply them. Stable/beta
 operations do not depend on an experimental public Analytics Ops contract.