feat: add anonymous telemetry

.changeset/anonymous-telemetry.md

@@ -0,0 +1,8 @@
+---
+"@caplets/core": minor
+"caplets": minor
+"@caplets/opencode": minor
+"@caplets/pi": minor
+---
+
+Add opt-out anonymous telemetry controls, privacy-gated event builders, Sentry/PostHog provider adapters, CLI status/debug commands, and stderr-only first-run disclosure for eligible CLI/runtime commands.

.github/workflows/release.yml

@@ -56,10 +56,12 @@ jobs:
         uses: changesets/action@v1
         with:
           version: pnpm version-packages
-          publish: pnpm release
+          publish: pnpm telemetry:prepare-release-env && pnpm release
           commit: "chore: version packages"
           title: "chore: version packages"
         env:
+          CAPLETS_POSTHOG_TOKEN: ${{ secrets.CAPLETS_POSTHOG_TOKEN }}
+          CAPLETS_SENTRY_DSN: ${{ secrets.CAPLETS_SENTRY_DSN }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Check whether CLI package was published

CONCEPTS.md

@@ -78,6 +78,12 @@ Recovery References are separate from session handles. Possessing a session hand
 
 The Caplets exposure mode where agents discover and call backend operations through a small set of wrapper tools instead of receiving every downstream operation as a separate top-level tool.
 
+### Anonymous Telemetry
+
+Opt-out Caplets usage and reliability reporting that uses a stable anonymous installation ID and categorical metadata only.
+
+Anonymous Telemetry is split by purpose: PostHog receives product usage events, while Sentry receives sanitized reliability events. It must not collect raw config, prompts, Code Mode code, tool arguments, tool outputs, paths, URLs, hostnames, Caplet IDs, credentials, or unsanitized error payloads.
+
 ## Remote Attach
 
 ### Remote Attach

README.md

@@ -188,6 +188,23 @@ caplets vault access grant GH_TOKEN github --remote
 Vault values are not exposed through Code Mode, progressive tools, or native agent APIs. Unset or
 ungranted Vault references quarantine only the affected Caplet and appear in `caplets doctor`.
 
+## Anonymous Telemetry
+
+Caplets collects opt-out anonymous telemetry for product usage and reliability. The first eligible
+interactive CLI run writes a notice to stderr only, including both disable controls:
+
+```sh
+CAPLETS_DISABLE_TELEMETRY=1 caplets serve
+caplets telemetry disable
+```
+
+Use `caplets telemetry status`, `enable`, `disable`, `rotate-id`, `delete-id`, and `debug` to
+inspect or control local telemetry. Caplets never collects raw config, prompts, Code Mode code, tool
+arguments, tool outputs, logs, file paths, URLs, hostnames, Caplet IDs, credentials, tokens, raw
+environment variables, raw error messages, or unsanitized stack traces. Rotating or deleting the
+local anonymous ID does not delete provider-side historical anonymous events; provider retention
+controls historical data.
+
 ## Benchmark
 
 The deterministic benchmark compares flat MCP exposure with Caplets over the same mock

apps/docs/src/content/docs/agent-integrations.mdx

@@ -41,6 +41,9 @@ claude mcp add --transport stdio --scope user caplets -- caplets serve
 OpenCode can use Caplets through MCP or the native OpenCode integration. Native mode exposes
 `caplets__code_mode` for Code Mode, plus progressive or direct tools only when configured.
 
+Native integrations use the shared anonymous telemetry controls and do not send telemetry on a
+native-first run until a visible CLI telemetry notice has already been recorded.
+
 Remote native usage:
 
 ```sh
@@ -52,6 +55,9 @@ CAPLETS_MODE=remote CAPLETS_REMOTE_URL=https://caplets.example.com/caplets openc
 Pi can use Caplets through MCP or the native Pi integration. Native mode uses the same local
 and remote selection rules as OpenCode.
 
+Native integrations use the shared anonymous telemetry controls and do not send telemetry on a
+native-first run until a visible CLI telemetry notice has already been recorded.
+
 Remote native usage:
 
 ```sh

apps/docs/src/content/docs/install.mdx

@@ -77,6 +77,28 @@ npx caplets doctor
 The output should show the active Caplets paths and any integration checks Caplets can
 run in this environment. Treat failed rows as setup work, not as agent bugs.
 
+## Anonymous telemetry
+
+Caplets collects opt-out anonymous telemetry for product usage and reliability. The first eligible
+interactive CLI run writes a notice to stderr only, so JSON stdout and MCP protocol output stay
+clean.
+
+Disable telemetry for one process:
+
+```sh
+CAPLETS_DISABLE_TELEMETRY=1 caplets serve
+```
+
+Disable it in your user Caplets config:
+
+```sh
+caplets telemetry disable
+```
+
+Inspect local state with `caplets telemetry status`. Caplets never collects raw config, prompts,
+Code Mode code, tool arguments, tool outputs, logs, file paths, URLs, hostnames, Caplet IDs,
+credentials, tokens, raw environment variables, raw error messages, or unsanitized stack traces.
+
 ## First agent check
 
 After `doctor` is clean enough for your integration, ask the agent:

apps/docs/src/content/docs/reference/config.mdx

@@ -62,22 +62,23 @@ Public OpenAPI endpoint:
 
 ## Top-level fields
 
-| Field                 | Status   | Type    | Description                                                   |
-| --------------------- | -------- | ------- | ------------------------------------------------------------- |
-| `$schema`             | Optional | string  | Optional JSON Schema for editor validation.                   |
-| `version`             | Optional | number  | Caplets config schema version.                                |
-| `defaultSearchLimit`  | Optional | integer | Default maximum number of same-server search results.         |
-| `maxSearchLimit`      | Optional | integer | Maximum accepted search_tools limit.                          |
-| `completion`          | Optional | object  | Shell completion discovery timeout and cache settings.        |
-| `options`             | Optional | object  | Global Caplets runtime options.                               |
-| `namespaceAliases`    | Optional | object  | Source-level namespace aliases for hash-qualified Caplet IDs. |
-| `mcpServers`          | Optional | object  | Downstream MCP servers keyed by stable server ID.             |
-| `openapiEndpoints`    | Optional | object  | OpenAPI endpoints keyed by stable Caplet ID.                  |
-| `googleDiscoveryApis` | Optional | object  | Google Discovery APIs keyed by stable Caplet ID.              |
-| `graphqlEndpoints`    | Optional | object  | GraphQL endpoints keyed by stable Caplet ID.                  |
-| `httpApis`            | Optional | object  | HTTP APIs keyed by stable Caplet ID.                          |
-| `cliTools`            | Optional | object  | CLI tools keyed by stable Caplet ID.                          |
-| `capletSets`          | Optional | object  | Nested Caplet collections keyed by stable Caplet ID.          |
+| Field                 | Status   | Type    | Description                                                            |
+| --------------------- | -------- | ------- | ---------------------------------------------------------------------- |
+| `$schema`             | Optional | string  | Optional JSON Schema for editor validation.                            |
+| `version`             | Optional | number  | Caplets config schema version.                                         |
+| `defaultSearchLimit`  | Optional | integer | Default maximum number of same-server search results.                  |
+| `maxSearchLimit`      | Optional | integer | Maximum accepted search_tools limit.                                   |
+| `telemetry`           | Optional | boolean | Set false to disable anonymous Caplets telemetry for this user config. |
+| `completion`          | Optional | object  | Shell completion discovery timeout and cache settings.                 |
+| `options`             | Optional | object  | Global Caplets runtime options.                                        |
+| `namespaceAliases`    | Optional | object  | Source-level namespace aliases for hash-qualified Caplet IDs.          |
+| `mcpServers`          | Optional | object  | Downstream MCP servers keyed by stable server ID.                      |
+| `openapiEndpoints`    | Optional | object  | OpenAPI endpoints keyed by stable Caplet ID.                           |
+| `googleDiscoveryApis` | Optional | object  | Google Discovery APIs keyed by stable Caplet ID.                       |
+| `graphqlEndpoints`    | Optional | object  | GraphQL endpoints keyed by stable Caplet ID.                           |
+| `httpApis`            | Optional | object  | HTTP APIs keyed by stable Caplet ID.                                   |
+| `cliTools`            | Optional | object  | CLI tools keyed by stable Caplet ID.                                   |
+| `capletSets`          | Optional | object  | Nested Caplet collections keyed by stable Caplet ID.                   |
 
 ## Major sections
 

apps/docs/src/content/docs/troubleshooting.mdx

@@ -64,6 +64,33 @@ CAPLETS_CONFIG=/path/to/caplets.json caplets doctor
 Project config should live at `.caplets/config.json`. User config is for personal agent
 setup; project config is for capabilities that should travel with a repository.
 
+### Disable or inspect telemetry
+
+Expected symptom: you want to disable anonymous telemetry, inspect local telemetry state, or see the
+sanitized events Caplets would send.
+
+Disable telemetry for one process:
+
+```sh
+CAPLETS_DISABLE_TELEMETRY=1 caplets doctor
+```
+
+Disable telemetry in your user Caplets config:
+
+```sh
+caplets telemetry disable
+```
+
+Inspect state or run a local debug capture:
+
+```sh
+caplets telemetry status
+caplets telemetry debug -- doctor
+```
+
+`caplets telemetry rotate-id` and `caplets telemetry delete-id` affect only the local anonymous ID.
+They do not delete provider-side historical anonymous events.
+
 ### Code Mode returns `ok: false`
 
 Expected symptom: a Code Mode call returns an error envelope instead of tool data.

apps/landing/public/config.schema.json

@@ -29,6 +29,10 @@
       "exclusiveMinimum": 0,
       "maximum": 50
     },
+    "telemetry": {
+      "description": "Set false to disable anonymous Caplets telemetry for this user config.",
+      "type": "boolean"
+    },
     "completion": {
       "default": {
         "discoveryTimeoutMs": 750,