diff --git a/cli-config.yaml.example b/cli-config.yaml.example
index 67264b1c0928..0821bcfcd2b7 100644
--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@@ -1408,6 +1408,8 @@ display:
 # Shared metrics are disabled by default. When enabled, Hermes writes only
 # allowlisted aggregate counters and immutable JSON
 # packages under $HERMES_HOME/telemetry/shared_metrics; it does not upload them.
+# Packages include a random profile-scoped ID that stays stable until this
+# directory is deleted. It is not derived from hardware, account, or host data.
 telemetry:
   shared_metrics:
     enabled: false
diff --git a/docs/observability/relay-shared-metrics.md b/docs/observability/relay-shared-metrics.md
index 60709c8c6409..b9dd9bd15a6a 100644
--- a/docs/observability/relay-shared-metrics.md
+++ b/docs/observability/relay-shared-metrics.md
@@ -74,6 +74,19 @@ The database keeps transactional aggregate and package-outbox state. Package
 files are immutable delta documents that conform to a closed JSON schema and
 are written with atomic replacement.
 
+Each package contains an `install_id` generated as a random UUID. Despite the
+schema field name, its current scope is one `HERMES_HOME`, so it is more
+precisely a persistent pseudonymous profile identifier. It is not derived from
+hardware, account, host, path, or credential data. It remains stable across
+packages from that profile and can therefore link those local packages.
+Deleting `$HERMES_HOME/telemetry/shared_metrics` resets the identifier together
+with all aggregates and package files.
+
+This slice has no remote-delivery path. A future remote exporter must not reuse
+the persistent local identifier by default. It requires a separate product and
+privacy decision covering consent, identity scope, rotation or keyed
+pseudonymization, reset behavior, retention, and deletion.
+
 ## Smoke Test
 
 Run a real Hermes CLI turn against the deterministic local model server:
diff --git a/hermes_cli/observability/schemas/hermes.shared_metrics.v1.schema.json b/hermes_cli/observability/schemas/hermes.shared_metrics.v1.schema.json
index 6c067d0eb8e7..68496e5ab6f3 100644
--- a/hermes_cli/observability/schemas/hermes.shared_metrics.v1.schema.json
+++ b/hermes_cli/observability/schemas/hermes.shared_metrics.v1.schema.json
@@ -22,6 +22,7 @@
       "$ref": "#/$defs/uuid"
     },
     "install_id": {
+      "description": "Random persistent identifier scoped to one HERMES_HOME; local-only in schema v1.",
       "$ref": "#/$defs/uuid"
     },
     "period_start": {