From bd3d94d98db90d1246bad0ea1df5a7f3d6ab9e96 Mon Sep 17 00:00:00 2001 From: Klappy Date: Sat, 18 Apr 2026 01:41:46 +0000 Subject: [PATCH] canon(telemetry): add Description column to Self-Report Fields table The canary refactor (klappy/oddkit#106) reads this table at runtime to populate telemetry_policy's self_report_headers response field. The prior 3-column schema (Field, Header, Source) gave callers only short labels ('Client name'); the hardcoded dictionary in the worker had richer per-field guidance ('Your client name (highest priority identifier)') that was lost when canon became the source of truth. Extending the table to 4 columns lets canon carry the authoritative per-header description. This is a DRY consolidation: the guidance lives in one place (here), the worker parses it at runtime, and updates flow through canon rather than code. Examples added per field (client names, surface identifiers, capability list format) so the table doubles as implementer docs for consumers wiring up their own telemetry headers. Related: klappy/oddkit#106 (canary refactor), klappy/klappy.dev#101 (core-governance-baseline contract draft). --- canon/constraints/telemetry-governance.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/canon/constraints/telemetry-governance.md b/canon/constraints/telemetry-governance.md index 97e19271..db53caa0 100644 --- a/canon/constraints/telemetry-governance.md +++ b/canon/constraints/telemetry-governance.md @@ -133,16 +133,16 @@ Modeled after the proven pattern in Aquifer MCP: ### Self-Report Fields (Optional, Incentivized) -| Field | Header | Source | -|-------|--------|--------| -| Client name | `x-oddkit-client` | Header or clientInfo | -| Client version | `x-oddkit-client-version` | Header or clientInfo | -| Agent name | `x-oddkit-agent-name` | Header | -| Agent version | `x-oddkit-agent-version` | Header | -| Surface | `x-oddkit-surface` | Header | -| Contact URL | `x-oddkit-contact-url` | Header | -| Policy URL | `x-oddkit-policy-url` | Header | -| Capabilities | `x-oddkit-capabilities` | Header | +| Field | Header | Source | Description | +|-------|--------|--------|-------------| +| Client name | `x-oddkit-client` | Header or clientInfo | Your client name (highest priority identifier). Examples: `claude-desktop`, `truthkit-cli`, `your-company-agent`. | +| Client version | `x-oddkit-client-version` | Header or clientInfo | Version string for the client above. Semver recommended but any stable identifier works. | +| Agent name | `x-oddkit-agent-name` | Header | The AI agent or model name when distinct from the client. Example: `claude-opus-4-7`. | +| Agent version | `x-oddkit-agent-version` | Header | Version string for the agent/model above. | +| Surface | `x-oddkit-surface` | Header | Where this is running. Examples: `claude.ai`, `vscode`, `cli`, `ci`, `production`. | +| Contact URL | `x-oddkit-contact-url` | Header | URL for your project or organization. Appears on the transparency leaderboard. | +| Policy URL | `x-oddkit-policy-url` | Header | Your privacy or telemetry policy URL. Signals reciprocal transparency. | +| Capabilities | `x-oddkit-capabilities` | Header | Comma-separated capability list describing what your client can do. Example: `read,write,vision`. | ### Completeness Scoring