[Epic] Measure NemoClaw adoption with privacy-bounded telemetry

## Summary

NemoClaw needs telemetry to understand how users install and configure the product. This information will guide compatibility, documentation, testing, and support investments.

This epic defines telemetry for:

- Completed installs and updates
- Configured environments
- Agent runtimes and exact configured-agent counts
- Model and inference-provider categories
- Messaging-channel configuration
- Selected configuration categories
- NemoClaw Community catalog page views and allowlisted interactions
- Country-level aggregate reporting

The client must not send identifiers for users, devices, installations, environments, sandboxes, or sessions. It must not send arbitrary model, provider, messaging, or configuration values.

Exact timestamps and network transport metadata can make events correlatable. Privacy approval of the complete collection service is therefore required before implementation.

## Relationship to OpenShell telemetry

NemoClaw follows OpenShell’s shared-product-client-ID, closed-category, default-on opt-out, and best-effort transport pattern.

OpenShell currently:

- Sends JSON events by default to `https://events.telemetry.data.nvidia.com/v1.1/events/json`.
- Permits `OPENSHELL_TELEMETRY_ENDPOINT` to replace or disable that default endpoint.
- Uses one shared OpenShell client ID across installations.
- Sets installation-like, user, device, integration, identity-provider, and session identifiers to `undefined`.
- Sends the exact client version, CPU architecture, event timestamp, and send timestamp.
- Sends exact numeric counts.
- Uses typed event constructors and closed provider-profile categories.
- Maps unrecognized providers and drivers to `custom` or `unknown`.
- Uses a bounded in-memory queue and a five-second HTTP timeout.
- Does not retry or persist failed events.
- Silently drops events when the queue is full, delivery fails, or the process exits before delivery.
- Defaults telemetry on and supports runtime opt-out and compile-time removal.
- Explicitly disables telemetry in its CI, canary, and end-to-end test configurations.
- Publishes aggregate reports that include country rankings.

The OpenShell client sends no country field. Country classification is added downstream. The public repository does not establish how the service creates that classification or handles source IP addresses.

The OpenShell repository also does not contain the NVIDIA collection service. It does not establish raw-event storage, transport-metadata retention, access controls, or deletion behavior.

NemoClaw will align with these OpenShell behaviors:

- Exact numeric counts
- Exact event and send timestamps
- Exact released client version
- CPU architecture
- Closed provider-profile categories
- One shared NemoClaw client ID
- Explicitly undefined entity identifiers
- Default-on telemetry with runtime opt-out
- Best-effort delivery without retries or persistent event storage on the client
- Country classification added downstream, not supplied by the client

NemoClaw will intentionally differ in these areas:

- NemoClaw adds install and update completion events.
- NemoClaw uses a fixed production endpoint. Release builds do not accept an endpoint override.
- NemoClaw public reports suppress or combine cells below an approved minimum count.
- NemoClaw requires an independently reviewed collection-service contract.

## Measurement principles

- Send only approved enums, booleans, public release keys, exact counts, and transport fields.
- Map unrecognized values to `other`, `custom`, or `unknown`.
- Never send or hash an arbitrary value.
- Do not assign a persistent or rotating identifier to an installation.
- Use one shared NemoClaw client ID. The client ID is not an authentication credential.
- Do not describe event counts as unique installations, users, environments, or active agents.
- Do not describe configured model or messaging state as runtime usage.
- A telemetry failure must not change an install, update, onboarding, or sandbox-lifecycle result.
- Public reporting must use aggregate values and an approved minimum report count.

## Proposed signals

| Signal | Available state | Transmitted fields | Important limitation |
| --- | --- | --- | --- |
| Install or update completion | The canonical installer has a success boundary after CLI verification, finalization, and cleanup | `operation`, exact released client version | Counts completed operations, not unique installations. Same-version repairs and ambiguous reruns do not emit. |
| Environment | Published sandbox registrations in the sandbox registry | Exact numeric `count` | Counts registry observations, not unique or running environments. |
| Agent runtime | Configured agent and expected version in each published sandbox registration | `agent_runtime`, exact numeric `count` | Identifies configured primary agent runtimes, not processes or internal subagents. |
| Managed agent version | Expected agent version and NemoClaw-managed image provenance | `agent_runtime`, `managed_agent_version`, exact numeric `count` | The version is configured build metadata, not a live binary probe. |
| Model | Recorded inference selection, provenance, provider, and API family | `model_source`, `known_model_key`, `provider_profile`, `api_family`, exact numeric `count` | Raw custom model IDs, provider aliases, and endpoints remain excluded. Recorded state can differ from the live route. |
| Messaging | Validated built-in channel entries in persisted messaging plans | `messaging_channel`, exact numeric `count` | Counts configured channel observations, not connected or healthy channels. |
| Configuration | Driver, GPU, policy tier, web search, observability, image provenance, and host platform | One closed `signal`, one allowlisted `value`, and an exact count when applicable | Arbitrary configuration values remain excluded. Related events can still be correlated by timestamps and transport metadata. |
| Country | No client-side geography field | Country-level aggregates created downstream | Country is an event-origin classification. It does not establish user residence or installation location. The derivation method requires review. |

## Transport and event envelope

The proposed default production endpoint is:

`https://events.telemetry.data.nvidia.com/v1.1/events/json`

The telemetry service must assign NemoClaw its own shared client ID and accepted schema. NemoClaw must not reuse OpenShell client ID `415437562476676`.

If NemoClaw uses the existing NVIDIA event service, the transport adapter will follow its registered wire contract. The expected OpenShell-style envelope includes:

- One shared `clientId`
- Exact `clientVer`
- `cpuArchitecture`
- Exact millisecond event timestamp
- Exact millisecond send timestamp
- One event in the `events` array
- Service-defined schema, protocol, and system versions
- `undefined` values for user, device, installation-like, integration, and session identifiers

The client must not send a credential or authorization secret. The shared client ID is public product metadata.

Every logical event also includes a closed event name and `nvidiaSource=nemoclaw`.

## Logical events

### `nemoclaw_install_completed`

Fields:

- `operation`: `install` or `update`

Classification occurs locally:

- No valid prior NemoClaw CLI: `install`
- Recognized older version or invocation from `nemoclaw update`: `update`
- Same-version repair, source checkout, CI, test, or ambiguous prior state: do not emit

The installer emits only after CLI verification, finalization, and required cleanup complete successfully.

### `nemoclaw_sandbox_count_observed`

Fields:

- `count`: an exact nonnegative integer

Only published sandbox registrations count. Pending route reservations do not count.

### `nemoclaw_agent_runtime_observed`

Fields:

- `agent_runtime`: `openclaw`, `hermes`, `langchain-deepagents-code`, or `other`
- `count`: an exact nonnegative integer

### `nemoclaw_managed_agent_version_observed`

Fields:

- `agent_runtime`
- `managed_agent_version`: a checked-in NemoClaw-managed release key or `other`
- `count`: an exact nonnegative integer

Custom images and unverified versions map to `other`.

### `nemoclaw_model_observed`

Fields:

- `model_source`: `product_catalog`, `provider_catalog`, `custom`, `local`, or `unknown`
- `known_model_key`: a checked-in product-owned telemetry key, `other`, or `unknown`
- `provider_profile`: an approved provider category, `custom`, or `unknown`
- `api_family`: `openai-completions`, `openai-responses`, `anthropic-messages`, or `unknown`
- `count`: an exact nonnegative integer

The initial provider-profile proposal is:

- `nvidia`
- `openai`
- `anthropic`
- `google-gemini`
- `openrouter`
- `hermes`
- `ollama`
- `vllm`
- `llama-cpp`
- `compatible-endpoint`
- `custom`
- `unknown`

NemoClaw must record explicit model provenance when durable state cannot distinguish model sources. The telemetry projector must not infer provenance from a raw model ID.

### `nemoclaw_messaging_observed`

Fields:

- `messaging_channel`: `telegram`, `discord`, `wechat`, `slack`, `whatsapp`, `teams`, `googlechat`, or `other`
- `count`: an exact positive integer

Count only channels recorded as configured in validated persisted plans for published environments. Do not inspect active or disabled state, credentials, configuration values, health, or traffic.

### `nemoclaw_configuration_observed`

Fields:

- `scope`: `host` or `sandbox`
- `signal`: one approved signal
- `value`: one value from that signal’s allowlist
- `count`: an exact nonnegative integer when the signal represents sandbox state

Initial signal allowlist:

| Signal | Values |
| --- | --- |
| `host_platform` | `linux`, `wsl`, `macos`, `other`, `unknown` |
| `compute_driver` | Approved driver IDs, `other`, `unknown` |
| `gpu_state` | `not_configured`, `configured_unverified`, `verified`, `failed`, `unknown` |
| `policy_tier` | `restricted`, `balanced`, `open`, `personal`, `other`, `unknown` |
| `web_search_enabled` | `true`, `false`, `unknown` |
| `observability_enabled` | `true`, `false`, `unknown` |
| `image_ownership` | `managed`, `custom`, `unknown` |

CPU architecture remains in the common event envelope. The client does not emit it again as a configuration signal.

## Client behavior

The proposed release behavior is default-on after plain installer and documentation disclosure.

The client must:

- Support a documented runtime opt-out.
- Evaluate the opt-out before reading registry state or constructing telemetry fields.
- Explicitly disable telemetry in NemoClaw CI, tests, canaries, and end-to-end test configurations.
- Send to one fixed production HTTPS endpoint.
- Permit test endpoint injection only through test-owned construction.
- Reject redirects.
- Retain no cookies.
- Send no query string.
- Use a bounded in-memory queue for long-running processes.
- Use a five-second total HTTP timeout.
- Make no retry.
- Store no client-side delivery outbox.
- Continue the product operation after queue, DNS, TLS, timeout, redirect, or HTTP failure.

The short-lived installer may make one bounded completion attempt after successful installation. It must not report success before installation cleanup completes.

## Collection and reporting contract

The first child issue must identify:

- Telemetry product owner
- Privacy owner
- Collection-service owner
- Operations owner
- Registered NemoClaw client ID
- Accepted wire schema
- Endpoint abuse controls
- Raw-event storage behavior
- Exact timestamp retention
- Source IP address and request-header handling
- Country-classification method
- Access controls and permitted joins
- Backup and deletion behavior
- Aggregate retention
- Public-report approval process

The contract must explicitly state whether the service stores event-level records. The Epic must not assume immediate aggregation or raw-event deletion because the OpenShell repository does not establish either behavior.

The client sends no country, IP address, or location field. The service may add country classification downstream only after the privacy owner accepts the method, retention, and access controls.

NemoClaw reporting consumers must receive aggregate results, not source IP addresses or unrestricted raw-event exports.

Public reports must suppress or combine cells below an approved minimum count. The proposed initial threshold is 20 observations. This is a stricter NemoClaw control; it is not current OpenShell reporting behavior.

If the selected service cannot meet the accepted privacy and reporting contract, implementation must stop.

## Excluded client data

The client must never transmit:

- User, device, installation, environment, sandbox, or session identifiers
- Stable or rotating installation pseudonyms
- Hashes of excluded data
- Raw custom model IDs
- Raw provider aliases or arbitrary provider names
- Inference endpoints or credential environment names
- Credentials or credential-presence metadata
- Sandbox names, hostnames, filesystem paths, or mount paths
- Image references, tags, or registry locations
- GPU models, hardware models, serial numbers, or hardware inventory
- Messaging account, workspace, team, room, channel, sender, or recipient identifiers
- Messaging credentials, credential bindings, or user-supplied configuration
- Arbitrary configuration keys or values
- Custom policy contents
- Errors, logs, stack traces, or user content
- IP addresses, request headers, or client-supplied geography fields
- Precise location
- Inference prompts, responses, token counts, or message contents

## Measurement semantics

Reports must use these terms:

- **Completed install operations**, not unique installations
- **Completed update operations**, not upgraded users
- **Environment observations**, not unique or active environments
- **Configured agent runtimes**, not active agents
- **Recorded model selections**, not model usage
- **Configured provider profiles**, not provider traffic
- **Configured messaging channels**, not connected channels or messaging usage
- **Configuration observations**, not complete environment profiles
- **Event-origin country**, not user residence or installation location

Exact counts describe one eligible observation. Repeated observations can count the same configuration again.

Network loss, process exit, queue saturation, opt-out, CI suppression, ambiguous state, and schema rejection cause undercounting.

Earlier OpenShell reports may include internal traffic because explicit CI suppression was added after telemetry launched. NemoClaw reports must distinguish product traffic from explicitly disabled internal environments.

## Open design decisions

The first child issue must resolve:

- Selected NVIDIA telemetry service and owning teams
- NemoClaw client ID and registered wire schema
- Privacy acceptance of exact timestamps and transport metadata
- Country-classification source and method
- Raw-event, transport-log, aggregate, and backup retention
- Default-on disclosure and persistent opt-out interface
- Whether `DO_NOT_TRACK=1` disables telemetry
- Observation triggers and maximum cadence
- Endpoint abuse controls for an unauthenticated client
- Final public-report minimum count
- Product-owned provider, model, and managed-version allowlists
- Regional disclosure or consent requirements

## Acceptance criteria

The epic is complete when:

- [ ] A maintainer records an accepted product decision, accountable maintainer, and validation plan.
- [ ] The telemetry product, privacy, service, and operations owners accept the complete contract.
- [ ] NemoClaw has a registered client ID and closed service schema.
- [ ] Release builds send only to the accepted fixed first-party endpoint.
- [ ] The envelope contains exact client version, CPU architecture, event timestamp, and send timestamp.
- [ ] User, device, installation-like, integration, and session identifiers use the service’s undefined value.
- [ ] Completed install and update operations emit only after successful completion.
- [ ] Environment, agent-runtime, model, messaging, and configuration events use exact numeric counts.
- [ ] Model events use explicit provenance, checked-in model keys, and approved provider profiles.
- [ ] Messaging events use built-in channel IDs from validated persisted plans without reading active, disabled, credential, health, or runtime state.
- [ ] Unknown and custom values map to approved fallback categories without hashing.
- [ ] The client sends no country or location field.
- [ ] The service’s downstream country classification is documented and approved.
- [ ] Raw-event, timestamp, source-IP, header, aggregate, backup, access, and deletion behavior is documented.
- [ ] Users receive plain disclosure and can disable telemetry.
- [ ] NemoClaw CI, tests, canaries, and end-to-end tests explicitly disable telemetry.
- [ ] Negative serialization tests prove that excluded values cannot enter a payload.
- [ ] Queue, DNS, TLS, timeout, redirect, and HTTP failures do not change product results.
- [ ] Public reports use approved measurement terms and suppress cells below the accepted threshold.
- [ ] Public documentation lists collected fields, exclusions, opt-out behavior, retention, geography handling, and measurement limitations.

## Proposed child issues

1. Define the NemoClaw telemetry privacy, service, and reporting contract.
2. Measure completed NemoClaw install and update operations.
3. Measure published environments and configured agent runtimes.
4. Measure model selections and approved provider profiles.
5. Measure configured messaging channels.
6. Measure selected configuration distributions.

Each child issue must deliver its metric end to end. Client projection, service schema, tests, disclosure, aggregation, and reporting semantics belong to the same child issue.

## Non-goals

- Unique installation, device, user, or environment counts
- Persistent or rotating installation identity
- Active-user measurement
- Internal subagent counts
- Inference or messaging traffic analytics
- Prompt, response, token, or message collection
- Raw custom model, provider, endpoint, or configuration inventory
- Precise geography
- Runtime health or availability monitoring
- Client-assigned correlation identifiers
- Per-install or per-user event timelines
- A user-configurable production telemetry destination
- A general-purpose telemetry SDK for third-party plugins