analytics_ops 0.2.0 → 0.3.0

data/docs/api-support-matrix.md

@@ -1,6 +1,6 @@
 # API support matrix
 
-This matrix describes Analytics Ops 0.2.0—not every method Google exposes.
+This matrix describes Analytics Ops 0.3.0—not every method Google exposes.
 
 | State | Meaning |
 | --- | --- |
@@ -10,7 +10,7 @@ This matrix describes Analytics Ops 0.2.0—not every method Google exposes.
 | Manual | Reported as an operator checklist |
 | Unsupported | Deliberately outside the public contract |
 
-| Capability | State | Exact 0.2.0 behavior |
+| Capability | State | Exact 0.3.0 behavior |
 | --- | --- | --- |
 | Account/property discovery | Audited | Lists accessible summaries without requiring configuration |
 | Data-stream discovery | Audited | Lists web, Android, and iOS streams without requiring configuration |
@@ -22,19 +22,34 @@ This matrix describes Analytics Ops 0.2.0—not every method Google exposes.
 | 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 |
+| Saved/custom report recipes | Audited | Strict YAML or bounded CLI definitions; property metadata and compatibility checked before execution |
+| Report metadata/compatibility | Audited | Property-aware field search and Google's `checkCompatibility` result |
+| Paginated CSV export | Audited | Streaming, atomic mode-0600 export with spreadsheet protection and a 1,000,000-row hard cap |
 | 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 |
+| Date overrides and comparison | Audited | Bounded complete-day or absolute ranges, with an equal preceding period |
+| Analytics health | Audited | Deterministic traffic, event, acquisition, quota, and configuration-drift checks |
+| Multi-property portfolio | Audited | Totals, arbitrary reports, and health across named profiles/connections; bounded concurrency and isolated failures |
+| Local MCP tools | Audited | 21 read-only discovery, audit, reporting, health, governance, portfolio, BigQuery, and funnel tools |
+| MCP mutation | Unsupported | No plan, apply, create, update, delete, or archive tool exists |
+| Enhanced Measurement | Experimental | Read-only per-web-stream governance audit plus validated declaration; 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 |
+| Stream data redaction | Experimental | Reads email/query redaction settings and audits explicit expectations; no mutation |
+| Reporting identity/attribution | Experimental | Read-only normalized snapshot; identity can be audited |
+| Channel groups/calculated metrics | Experimental | Lists resources and audits expected display names; no mutation |
+| Event create/edit rules | Experimental | Lists rules under each web stream and audits expected names; no mutation |
+| BigQuery links | Experimental | Lists existing links and can require at least one; no create/update/delete |
+| Change history | Experimental | Bounded account/property request; omits actor email and full before/after resources |
+| Data Access report | Experimental | Aggregate `accessDateHour` and Data API token usage only; requires GA4 Administrator |
+| GA4 BigQuery export queries | Experimental | Optional official client, fixed SELECT recipes, dry run, mandatory byte cap, bounded results |
+| Ordered funnels | Experimental | Optional aggregate BigQuery sequence over 2–10 configured event steps; no user identifiers returned |
 | User-provided data setting | Unsupported | Not read or changed |
-| Event create/edit rules | Unsupported | Alpha, outside 0.2.0 |
-| Audiences and expanded datasets | Unsupported | Alpha, outside 0.2.0 |
+| Audiences and expanded datasets | Unsupported | Alpha, outside 0.3.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 |
+| BigQuery arbitrary SQL | Unsupported | No public Ruby, CLI, or MCP arbitrary-SQL input |
 | Measurement Protocol secrets/events | Unsupported | Never managed |
 | Account/property/stream deletion | Unsupported | No destructive path |
 
@@ -42,7 +57,9 @@ Google marks some Admin API capabilities as Alpha and warns that Alpha
 contracts may break. Analytics Ops never labels a capability managed merely
 because a generated class exists. The supported operations above have
 executable protobuf-coercion contract specs against the pinned official Ruby
-clients.
+clients. Optional BigQuery support is labeled experimental for a different
+reason: it has a separate dependency, permissions, export prerequisite, and
+query cost even though every template is read-only and capped.
 
 References:
 

data/docs/architecture.md

@@ -1,7 +1,7 @@
 # Architecture
 
 Analytics Ops is a plain-Ruby library and CLI with optional Rails hooks. It has
-no database and keeps Google's generated classes behind two narrow adapters.
+no database and keeps Google's generated classes behind narrow adapters.
 
 ```text
 strict YAML
@@ -14,13 +14,36 @@ strict YAML
 
 immutable report definition
   → Data API adapter
+  → metadata + compatibility validation for custom definitions
   → immutable normalized result
+  → optional bounded streaming CSV
+
+health policy
+  → batched current/previous reports + configuration plan
+  → deterministic findings
+
+experimental governance policy
+  → read-only Alpha Admin resources
+  → normalized snapshot + findings
+
+optional BigQuery recipe or funnel
+  → fixed parameterized SELECT
+  → dry run + mandatory byte cap
+  → bounded aggregate result
 
 configuration-free connection
   → explicit service-account identity
   → account/property discovery
   → API access verification
   → atomic minimal configuration
+
+named local connections + profiles
+  → selected property
+  → single-property workspace or read-only portfolio
+
+local MCP stdio
+  → read-only tool allowlist
+  → Workspace and generalized Portfolio
 ```
 
 ## Core objects
@@ -28,7 +51,7 @@ configuration-free connection
 | Object | Responsibility |
 | --- | --- |
 | `Configuration` | Bounded safe YAML, environment interpolation, schema validation |
-| `Configuration::Writer` | Non-destructive atomic creation of the smallest valid setup file |
+| `Configuration::Writer` | Non-destructive atomic creation or additive profile update |
 | `DesiredState` | Immutable configuration for one profile |
 | `Resources` | Gem-owned account/property/stream/settings values |
 | `Snapshot` | Canonical managed remote state and SHA-256 fingerprint |
@@ -38,25 +61,42 @@ configuration-free connection
 | `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 |
+| `Reports::Metadata` | Property-aware fields and compatibility results |
+| `Reports::CSVExport` | Atomic mode-0600 streaming pagination output |
+| `Health` | Deterministic traffic, event, quota, and drift findings |
+| `Governance` | Experimental normalized Alpha settings and policy findings |
+| `BigQuery::Definition` | Fixed optional raw-data recipe and hard result bounds |
+| `Clients::BigQuery` | Optional official client, dry run, byte cap, and normalized result |
+| `Funnels::Definition` | Strict aggregate ordered-event steps |
 | `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 |
+| `Portfolio` | Read-only totals, reports, and health across configured profiles and connections |
+| `Reports::Period` | Bounded simple dates and equal preceding-period comparisons |
+| `MCPServer` | Local strictly read-only AI tools over Workspace and Portfolio |
 | `CLI` | Option validation, formats, stable statuses, and explicit confirmation |
 | `Railtie` | Optional generator and operator Rake tasks |
 
 ## Dependency direction
 
 Domain and planning code know nothing about protobufs, gRPC, Rails, Active
-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`,
+Support, authentication flows, or HTTP transports. Admin, Data, and optional
+BigQuery 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 Analytics wrapper gems lazily. The optional
+`google-cloud-bigquery` client is not a runtime dependency and is loaded only
+when a configured raw report or funnel runs. 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.
 
+The MCP protocol implementation uses the official Ruby MCP SDK. Starting the
+server lists local tools only; credentials and Google clients remain lazy
+until a tool is called.
+
 ## State model
 
 Google Analytics is the remote source of truth. There is no local state
@@ -65,10 +105,11 @@ 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.
+verifies the selected property, and creates or additively updates the existing
+versioned YAML format. Existing conflicting profiles are never rewritten. A
+separate user-level `connection.json` stores named absolute service-account
+key paths and per-configuration profile selections. 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
@@ -85,8 +126,9 @@ Expected failures become typed Analytics Ops errors:
 - quota, timeout, invalid request, and remote failure
 - partial apply with a structured result
 
-Messages are redacted before user-visible output. Callers do not need to parse
-Google exception text.
+Messages are redacted before user-visible output. Structured Google reason,
+metadata, and status values are preserved in bounded Analytics Ops errors so
+setup does not need to recognize English wording.
 
 An injected logger receives small JSON request events containing only the
 service method and target resource. Request bodies, authorization data, and
@@ -99,9 +141,28 @@ report results are never logged automatically. CLI logging defaults to
 Engine, model, migration, route, controller, view, asset, or boot-time network
 call. Browser analytics and consent remain application concerns.
 
+## AI boundary
+
+`analytics-ops mcp` is a local stdio server. Its tool registry contains only
+property discovery, field/recipe discovery, health checks, snapshots, audits,
+overviews, generalized portfolios, bounded reports, governance, optional
+fixed BigQuery/funnel reads, and realtime reads. Every tool is marked
+read-only and non-destructive. Plan creation, plan-file writing, apply,
+create, update, delete, arbitrary SQL, and change history are absent rather
+than hidden behind model instructions.
+
+Tool outputs can contain analytics configuration and report rows. The chosen
+AI product receives those requested outputs, but never the service-account
+key, token, authorization header, or saved key path.
+
 ## Experimental boundary
 
-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.
+Google identifies several governance capabilities as Alpha. Version 0.3.0
+reads them only after an explicit experimental policy is configured, or when
+the operator directly runs an experimental command. They never enter an
+ordinary plan or apply.
+
+Optional BigQuery support is a separate experimental boundary. The public API
+accepts only fixed recipes and configured funnel steps, never SQL. Every query
+is dry-run first, is rejected above a configured byte maximum, and returns a
+bounded result without user identifiers.

data/docs/authentication.md

@@ -53,9 +53,10 @@ Analytics Ops writes this user-level file:
 ~/.config/analytics_ops/connection.json
 ```
 
-It contains only the absolute path to the service-account key. The connection
+It contains named connections, each holding only an absolute key path, plus
+the selected profile/connection for each configuration file. The connection
 file is created atomically with mode `0600`, and its directory uses mode
-`0700`. Analytics Ops does not copy the key or place its contents in project
+`0700`. Analytics Ops does not copy a key or place its contents in project
 configuration.
 
 Keep the key in a stable location. Moving or deleting it requires setup again:
@@ -66,7 +67,37 @@ analytics-ops setup \
 ```
 
 One service account can access several GA4 accounts. Add the same
-service-account email at account level in each GA4 account.
+service-account email at account level in each GA4 account. If different
+clients provide different service accounts, save each one under a clear name:
+
+```bash
+analytics-ops setup \
+  --profile client_a \
+  --connection client_a \
+  --service-account /secure/client-a/service-account.json
+
+analytics-ops setup \
+  --profile client_b \
+  --connection client_b \
+  --service-account /secure/client-b/service-account.json
+```
+
+Then switch without re-entering a key path:
+
+```bash
+analytics-ops connections
+analytics-ops profiles
+analytics-ops use client_b
+analytics-ops overview
+```
+
+`connections` never prints credential paths. `profiles` shows only profile
+names, property IDs, and connection names. An older version-1 single-key
+connection file is read automatically and upgraded on the next successful
+write. If two separate apps both use the default `production` profile with
+different keys, Analytics Ops automatically chooses a collision-free
+connection name instead of repointing the first app. Use `--connection NAME`
+when you want a clearer client name.
 
 ## Read and edit access
 
@@ -80,6 +111,22 @@ Analytics Ops still requires a saved plan, explicit confirmation, and a fresh
 matching snapshot before any apply. Merely configuring an Editor identity
 does not cause writes.
 
+Google also requires the edit scope to read configuration change history.
+`analytics-ops changes` uses an edit-scoped Admin client but contains no
+mutation call. Its result omits actor email and full before/after resource
+bodies.
+
+## Optional BigQuery access
+
+Normal Analytics commands never request a BigQuery scope. When a configured
+`raw` report or funnel runs, the optional adapter requests only
+`bigquery.readonly`.
+
+OAuth scope and Cloud IAM are separate. The service account also needs narrow
+permission to create query jobs in the configured project and read the GA4
+export dataset. It does not need Cloud Owner or Editor. See
+[BigQuery reports and funnels](bigquery.md).
+
 ## Automation
 
 Use the same service-account setup non-interactively:
@@ -136,6 +183,9 @@ GA4 data or settings.
 
 - Never place the JSON key or its path in `analytics_ops.yml`.
 - Never commit a service-account key.
+- Protect the key with `chmod 600` on macOS and Linux.
+- Keep the key outside every Git repository. Setup and `doctor` warn when
+  permissions or placement look unsafe.
 - Never paste key contents into chat, issues, logs, screenshots, or reports.
 - Never place production mutation credentials in a Rails web container.
 - Revoke and replace a key immediately if it may have been exposed.

data/docs/bigquery.md

@@ -0,0 +1,128 @@
+# Optional BigQuery reports and funnels
+
+You do not need BigQuery for normal Analytics Ops reports, overview, health,
+audit, or AI access.
+
+Use this optional feature only when you need GA4's exported event-level data,
+such as a true ordered funnel. The output remains aggregate or deliberately
+limited; Analytics Ops does not expose user identifiers.
+
+## What you need
+
+1. Link the GA4 property to BigQuery and wait for export tables named
+   `events_YYYYMMDD`.
+2. Enable the BigQuery API in the Google Cloud project that will run queries.
+3. Give the service account:
+   - permission to create query jobs in the configured billing project
+   - read access to the GA4 export dataset
+4. Add the optional official Ruby client to your application:
+
+```ruby
+gem "google-cloud-bigquery", "~> 1.64", group: :development
+```
+
+```bash
+bundle install
+```
+
+The service account does not need Cloud Owner or Editor. Use narrow BigQuery
+job-user and dataset-viewer permissions.
+
+## Cost-capped configuration
+
+All identifiers here are fake:
+
+```yaml
+profiles:
+  production:
+    property_id: "123456789"
+
+    bigquery:
+      experimental: true
+      project_id: example-analytics-project
+      dataset: analytics_123456789
+      location: US
+      maximum_bytes_billed: 1000000000
+```
+
+`maximum_bytes_billed` is mandatory. The value above is one billion bytes.
+Choose a limit that matches your cost policy.
+
+## Fixed raw-data recipes
+
+Analytics Ops accepts names, not arbitrary SQL:
+
+```bash
+analytics-ops raw event_counts --last 7
+analytics-ops raw daily_events --last 30
+analytics-ops raw page_views --last 7 --csv
+analytics-ops raw event_sample --last 1 --limit 100 --json
+```
+
+Available recipes:
+
+| Recipe | Result |
+| --- | --- |
+| `event_counts` | Event names and counts |
+| `daily_events` | Total events by export date |
+| `page_views` | Page URLs with query strings removed and view counts |
+| `event_sample` | A bounded sample of event time, name, platform, and device category |
+
+The maximum result limit is 10,000 rows. Comparison ranges are not accepted.
+
+## Ordered funnels
+
+Define a funnel with two through ten event steps:
+
+```yaml
+profiles:
+  production:
+    property_id: "123456789"
+
+    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: Began checkout
+            event_name: begin_checkout
+          - name: Purchased
+            event_name: purchase
+```
+
+```bash
+analytics-ops funnel checkout --last 30
+```
+
+The query uses `user_pseudo_id` and event timestamps only inside BigQuery to
+prove step order. The returned result contains only step name, aggregate user
+count, and completion rate.
+
+## Cost and mutation safety
+
+Every query:
+
+1. uses a fixed `SELECT` template
+2. passes dates and limits as parameters
+3. performs a BigQuery dry run
+4. refuses the query if estimated bytes exceed your configured limit
+5. sends the same `maximum_bytes_billed` limit on the real query job
+6. returns a bounded, normalized result
+
+Running a query creates an ephemeral BigQuery job and can incur query charges.
+It does not update or delete the GA4 export tables. Analytics Ops has no
+arbitrary-SQL public method or CLI option.
+
+Official references:
+
+- [GA4 BigQuery Export](https://support.google.com/analytics/answer/9358801)
+- [BigQuery query jobs](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-bigquery/latest/Google-Cloud-Bigquery-Project#query_job-instance_method)
+- [Maximum bytes billed](https://docs.cloud.google.com/bigquery/docs/best-practices-costs#restrict-query-costs)

data/docs/commands.md

@@ -13,16 +13,24 @@ analytics-ops COMMAND [options]
 ```bash
 analytics-ops setup --service-account /absolute/path/to/service-account.json
 analytics-ops overview
+analytics-ops overview --last 7 --compare
+analytics-ops portfolio
+analytics-ops portfolio report traffic
+analytics-ops health
 analytics-ops properties
 analytics-ops doctor
 analytics-ops audit --json
 analytics-ops plan --output tmp/ga4-plan.json
 analytics-ops apply tmp/ga4-plan.json
 analytics-ops report landing-pages --csv
+analytics-ops fields event
 analytics-ops realtime --json
+analytics-ops profiles
+analytics-ops mcp --config /absolute/path/to/config/analytics_ops.yml
 ```
 
-Only `apply` can write to Google.
+Only `apply` changes GA4 configuration. Optional `raw` and `funnel` commands
+create read-only BigQuery query jobs and can incur a bounded query cost.
 
 ## Setup
 
@@ -39,13 +47,15 @@ pass the downloaded JSON key explicitly. Setup then:
 4. Proves Admin and Data API read access.
 5. Creates the smallest valid `config/analytics_ops.yml` using the
    `production` profile.
-6. Stores only the key's absolute path in
+6. Stores a named connection containing only the key's absolute path in
    `~/.config/analytics_ops/connection.json` with mode `0600`.
 7. Prints `analytics-ops overview` as the next command.
 
 Setup never overwrites an existing profile that targets another property. A
-matching file is a successful no-op. The key is never copied into a project or
-printed.
+matching file is a successful no-op. A missing profile is appended safely
+without removing existing settings or comments. The untouched Rails generator
+placeholder is filled automatically. The key is never copied into a project
+or printed.
 
 Later setup runs use the remembered path:
 
@@ -66,6 +76,26 @@ analytics-ops setup \
 The CLI never consults `gcloud`, browser login, Application Default
 Credentials, `GOOGLE_APPLICATION_CREDENTIALS`, or API keys.
 
+## Profiles and connections
+
+Use a profile for each GA4 property and a named connection for each Google
+service account:
+
+```bash
+analytics-ops setup \
+  --profile client_b \
+  --connection client_b \
+  --service-account /secure/client-b/service-account.json
+
+analytics-ops profiles
+analytics-ops connections
+analytics-ops use client_b
+```
+
+`use` remembers the selected profile and its connection for this configuration
+file. Later commands use it automatically. Add `--profile NAME` or
+`--connection NAME` for a one-command override.
+
 ## Commands that do not change GA4
 
 | Command | Result |
@@ -75,17 +105,38 @@ Credentials, `GOOGLE_APPLICATION_CREDENTIALS`, or API keys.
 | `doctor` | Checks the local file, credentials, Admin API, Data API, property access, client versions, edit visibility, and clock |
 | `discover` | Lists accessible account IDs, property IDs, and stream IDs without configuration |
 | `overview` | Returns five bounded reports for the previous 28 complete days in one batch request |
+| `portfolio` | Returns users, sessions, and key events across every configured property |
+| `portfolio report NAME` | Runs one built-in or saved report across all profiles with isolated failures |
+| `portfolio health` | Runs deterministic health checks across all profiles with isolated failures |
+| `health` | Checks traffic, expected events, attribution quality, quota, and configuration drift |
 | `snapshot` | Prints normalized managed remote state and its fingerprint |
 | `audit` | Compares desired state with a fresh snapshot; exits 2 for drift |
 | `plan` | Generates the same comparison; `--output FILE` saves its exact JSON |
 | `verify` | Replans and exits 0 only when managed state converges |
-| `report NAME` | Runs one built-in standard Data API report |
+| `report NAME` | Runs one built-in or saved standard Data API report |
+| `report custom` | Builds a property-validated one-off report from CLI field options |
+| `reports` | Lists built-in and saved report recipes |
+| `fields [SEARCH]` | Searches property-aware Data API dimensions and metrics |
+| `compatibility NAME` | Checks whether one report's fields work together |
 | `realtime [NAME]` | Runs `realtime_events` by default |
+| `governance` | Audits broader read-only GA4 Admin settings; experimental |
+| `changes` | Reads bounded, de-identified change history; experimental and requires edit scope |
+| `access` | Reads aggregate Data API quota usage without user-email/IP fields; experimental |
+| `raw NAME` | Runs one fixed, dry-run-checked BigQuery recipe; experimental and optional |
+| `funnel NAME` | Runs one configured aggregate ordered funnel in BigQuery; experimental and optional |
+| `profiles` | Lists local profiles, property IDs, and connection names without contacting Google |
+| `connections` | Lists connection names and key availability without printing paths |
+| `use NAME` | Selects one local profile/connection without contacting Google |
+| `mcp` | Starts the strictly read-only local AI tool server |
 | `schema` | Prints the version-1 configuration schema |
 
 `doctor` uses the read-only Analytics scope and proves effective access with
 small real calls to both APIs.
 
+Google requires `analytics.edit` to read change history. The `changes`
+implementation uses that scope but exposes no mutation method and removes
+actor email and full before/after resources from its result.
+
 ## Apply
 
 ```bash
@@ -110,16 +161,76 @@ analytics-ops apply tmp/ga4-plan.json --non-interactive --yes --format json
 `--non-interactive` without `--yes` is an error. There is no command that
 plans and applies in one step.
 
+JSON apply is deliberately non-interactive. It requires both flags so a prompt
+can never corrupt the JSON stream:
+
+```bash
+analytics-ops apply tmp/ga4-plan.json --json --non-interactive --yes
+```
+
+## Report dates and comparisons
+
+The default remains the previous 28 complete days. Override it with one easy
+form:
+
+```bash
+analytics-ops report traffic --last 7
+analytics-ops report traffic --from 2026-07-01 --to 2026-07-07
+analytics-ops overview --last 30 --compare
+analytics-ops portfolio --last 30 --compare
+```
+
+`--compare` adds an equally long preceding period. Google returns a
+`dateRange` column labeled `current` or `previous`. Date options work with
+`report`, `overview`, `portfolio`, `health`, `raw`, and `funnel`. Health
+always adds the preceding comparison period. Raw and funnel
+reports accept only one period. Realtime reports have no date range. `--last`
+accepts 1 through 1,825 complete days.
+
+## Custom reports and exports
+
+```bash
+analytics-ops report custom \
+  --dimension eventName \
+  --metric eventCount \
+  --where eventName=purchase \
+  --limit 100
+
+analytics-ops report traffic \
+  --all \
+  --page-size 100000 \
+  --max-rows 500000 \
+  --output tmp/traffic.csv
+```
+
+`--where` is a repeatable exact dimension filter. Saved YAML recipes support
+the complete bounded filter model. `--all` is a streaming CSV export, requires
+an output path, and never exceeds `--max-rows`.
+
 ## Options
 
 | Option | Meaning |
 | --- | --- |
 | `-c, --config PATH` | Configuration file |
 | `-p, --profile NAME` | Profile inside the file |
-| `-f, --format FORMAT` | `human`, `json`, or report-only `csv` |
+| `--connection NAME` | Named saved Google connection |
+| `-f, --format FORMAT` | `human`, `json`, or result-only `csv` |
 | `--json` | Shortcut for `--format json` |
 | `--csv` | Shortcut for `--format csv` |
-| `-o, --output PATH` | Save generated JSON; valid only with `plan` |
+| `--last DAYS` | Previous complete days for date-aware read commands |
+| `--from DATE` | Inclusive `YYYY-MM-DD` start; requires `--to` |
+| `--to DATE` | Inclusive `YYYY-MM-DD` end; requires `--from` |
+| `--compare` | Include the equally long preceding period |
+| `-o, --output PATH` | Save a plan, or the CSV created by `report --all` |
+| `--dimension NAME` | Repeatable dimension for `report custom` |
+| `--metric NAME` | Repeatable metric for `report custom`; at least one required |
+| `--where FIELD=VALUE` | Repeatable exact dimension filter for `report custom` |
+| `--limit ROWS` | Row limit for `report custom` or `raw` |
+| `--all` | Page and stream a report to an explicit CSV output path |
+| `--max-rows ROWS` | Hard export limit; maximum 1,000,000 |
+| `--page-size ROWS` | Export rows per Data API request; maximum 250,000 |
+| `--kind dimension\|metric` | Restrict `fields` results |
+| `--concurrency COUNT` | Portfolio report/health workers; 1 through 8 |
 | `--property ID` | Select an accessible property without prompting; setup only |
 | `--service-account PATH` | Connect a Google service-account JSON key; setup only |
 | `--transport grpc|rest` | Official Google-client transport |
@@ -129,21 +240,31 @@ plans and applies in one step.
 | `--non-interactive` | Never prompt; apply requires `--yes`, setup requires `--property` |
 
 Unknown arguments, conflicting format flags, and non-finite timeouts fail
-instead of being ignored. CSV is rejected for anything except report results.
-CSV cells whose first meaningful character is a spreadsheet formula marker
-are prefixed safely, including cells hidden behind whitespace or controls.
+instead of being ignored. CSV is rejected for anything except report,
+portfolio-report, BigQuery, or funnel results. CSV cells whose first meaningful
+character is a spreadsheet formula marker are prefixed safely, including cells
+hidden behind whitespace or controls.
 
 ## Output
 
 - Human output removes terminal control characters from remote text.
+- Long human table cells keep both their beginning and ending, with an
+  ellipsis in the middle so similar URLs remain distinguishable.
+- Interactive apply prints complete redacted before/after values without the
+  ordinary message-length cap.
 - JSON output uses stable gem-owned fields and structured errors.
-- CSV contains one report's headers and rows only; it is rejected for batched
-  overviews, plans, snapshots, and errors.
+- CSV contains only result headers and rows. Portfolio CSV adds profile,
+  property, and label columns, and refuses partial portfolio results. CSV is
+  rejected for batched overviews, plans, snapshots, and errors.
 
 No command prints credentials or generated Google protobuf objects. Report
 rows are emitted only because the user requested a report; they are never
 logged automatically.
 
+The MCP command writes protocol messages to standard output and rejects human,
+JSON, or CSV formatting flags. Its advertised tools are all annotated
+read-only and include no plan or apply operation.
+
 ## Exit statuses
 
 | Status | Meaning |