Add privacy-preserving product telemetry and decision feedback loop

> 🤖 Generated by the Agentic Engineer

## Summary

Add privacy-preserving product telemetry across every KSail user surface: CLI, terminal UI (TUI), VS Code extension/plugin, MCP, desktop app, and web UI. The completed capability is enabled by default, has a prominent and reliable opt-out, sends a small versioned event set to a platform-hosted ingestion path, and gives the Agentic Engineer read-only aggregate evidence for future product decisions.

## Motivation

KSail decisions currently rely heavily on issues, pull requests, CI, and maintainer testing. Those sources show what is reported and what the test suite exercises, but not how the broader product is actually used or where users encounter friction.

We need aggregate evidence for questions such as:

- Which CLI commands, TUI workflows, VS Code extension actions, cluster providers, GitOps engines, and other user surfaces are used?
- Which operations succeed, fail, or take unusually long?
- Which stable error classes recur after a release?
- How fragmented is usage across KSail versions, operating systems, and architectures?
- Which capabilities appear unused, confusing, or unexpectedly valuable?

This evidence must improve product direction without collecting cluster contents, workload data, credentials, or personal information.

## Proposed solution

Define a versioned, OpenTelemetry-compatible product event contract and send events asynchronously to a KSail telemetry ingestion service hosted on the platform.

The initial allow-listed event set should cover:

- KSail version, operating system, architecture, and invoking surface: CLI, TUI, VS Code extension/plugin, MCP, desktop app, or web UI.
- Command or workflow family and selected provider or engine from a fixed vocabulary. TUI events describe a screen/action category rather than keypresses or entered values; VS Code events describe extension command/feature categories rather than editor contents, workspace paths, or command payloads.
- Completion outcome, a stable sanitized error class, and coarse duration buckets.
- Explicit feature or experimental-gate usage where it helps evaluate graduation decisions.

Telemetry must be best-effort and non-blocking. An unavailable or slow collector must never change command output, exit status, cluster behavior, or normal cleanup. Use bounded timeouts, bounded buffering, and conservative retry behavior with no unbounded local queue.

### Default and opt-out behavior

The final shipped behavior is enabled by default. Users must have one documented, durable opt-out that applies consistently across CLI, TUI, VS Code extension/plugin, MCP, desktop app, and web UI, plus a standard automation-friendly environment override such as `DO_NOT_TRACK=1`. The VS Code setting and TUI configuration must resolve through the same effective telemetry state rather than drifting into independent defaults. A status surface must show whether telemetry is enabled and how to disable it.

After opt-out, KSail emits no telemetry, including no event announcing that the user opted out. Tests must prove the zero-emission boundary.

### Privacy and security boundary

The first version must not collect:

- Names or contents of clusters, namespaces, workloads, repositories, files, paths, registries, or configuration.
- Kubeconfigs, manifests, logs, raw errors, raw arguments, URLs, IP addresses, credentials, tokens, user names, email addresses, or other free-form text.
- A stable user, machine, or installation identifier. Any future proposal for pseudonymous identity requires a separate privacy decision and cannot enter this epic implicitly.

The platform ingestion path must enforce transport encryption, schema validation, rate limits, abuse controls, explicit retention, and deletion. Raw events remain private; public roadmap artifacts may cite only aggregates that cannot identify an individual installation.

### Agentic Engineer feedback loop

Expose a documented read-only aggregate query or dashboard to the Agentic Engineer and add it to the KSail product-maintenance contract. The engineer should use it during monthly strategy review and when investigating adoption or error-rate regressions to create, rank, validate, or close roadmap issues.

Telemetry is one evidence source, not an automatic product oracle. Missing, delayed, or unhealthy ingestion is `QUERY-UNKNOWN`, never zero usage. The engineer must cross-check aggregates with user reports, reliability evidence, security constraints, and product goals.

## Phased delivery

The completed product is default-on, but implementation follows feature-flag-first delivery:

1. Define the event/privacy contract and platform architecture.
2. Ship an internal or canary path default-off and test both states.
3. Prove ingestion, dashboards, retention, opt-out, and failure isolation end to end.
4. Flip the default on in a separate reversible change with release notes and documentation.
5. After a representative observation window, publish a sanitized baseline and use it in the next KSail strategy review.

## Acceptance criteria

- [ ] An ADR under `docs/adr/` defines event semantics, privacy boundaries, schema versioning, retention, threat model, and rollout/rollback behavior.
- [ ] A small allow-listed event schema is shared by CLI, TUI, VS Code extension/plugin, MCP, desktop app, and web UI; arbitrary attributes and free-form payloads are rejected.
- [ ] The TUI and VS Code extension/plugin have explicit adapters and tests for their own workflow/feature categories while reusing the same schema version, privacy filter, delivery bounds, and effective opt-out state.
- [ ] The platform hosts a production-ready ingestion, storage, and aggregate dashboard path with health monitoring and bounded retention.
- [ ] Telemetry delivery is asynchronous and bounded; collector failure cannot change KSail behavior, output, exit status, or materially delay a command.
- [ ] Internal/default-off and final/default-on states are both tested; the epic is not complete until default-on ships.
- [ ] A durable config opt-out and `DO_NOT_TRACK=1` disable every event across every surface, including TUI and VS Code extension/plugin activity, with regression tests proving zero collector requests.
- [ ] Documentation clearly explains what is collected, what is never collected, why it is collected, retention, the platform operator, and how to inspect or disable it.
- [ ] Tests reject secrets, identifiers, paths, URLs, raw arguments, raw errors, and other non-allow-listed data before serialization.
- [ ] End-to-end verification observes a canary event in the aggregate backend and proves an opted-out invocation produces no collector request.
- [ ] The Agentic Engineer has a documented read-only aggregate view, a health check, and a defined strategy-review cadence; unhealthy telemetry remains `QUERY-UNKNOWN`.
- [ ] The first representative observation window produces a sanitized baseline covering feature adoption, error classes, latency buckets, version fragmentation, and concrete roadmap follow-ups.

## Proposed child issues

1. Define the telemetry ADR, event schema, privacy model, and opt-out contract.
2. Implement the non-blocking telemetry core plus CLI, TUI, VS Code extension/plugin, MCP, desktop app, and web UI adapters with cross-surface opt-out tests.
3. Build the platform ingestion, retention, health, and aggregate dashboards.
4. Integrate read-only telemetry evidence into Agentic Engineer KSail maintenance.
5. Validate the canary, flip default-on, document the release, and publish the baseline.

## Alternatives considered

- **Local-only logs:** useful for individual debugging but provide no aggregate product evidence.
- **Crash reporting only:** misses successful usage, slow paths, and confusing features that users abandon without a crash.
- **Opt-in by default:** minimizes collection but creates strong selection bias and does not satisfy the intended representative product feedback loop.
- **Third-party analytics SaaS:** unnecessary while the platform can own ingestion, retention, access, and privacy controls.

## Rough size

XL roadmap epic, expected to be delivered through approximately five independently shippable child issues.

Start with the proposed child issues and the ADR location under docs/adr/, beginning with the telemetry event, privacy, and opt-out contract. Review the acceptance criteria to define completion: shared allow-listed schema, bounded delivery, cross-surface opt-out tests, ingestion and aggregate evidence, documentation, and a default-on rollout.

Written by the indexing model from the issue text.