docs: add telemetry instrumentation guide

Author: Hweinstock

.github/harness/prompts/review.md

@@ -25,3 +25,5 @@ comment on the PR saying it looks good to merge (or that all issues have already
 - **Excessive mocking** — Avoid excessive mocking; it couples tests to implementation details, provides weaker
   guarantees, and often points to mismanaged dependencies. Prefer real dependencies (e.g. temp directories over fs
   mocks) and only mock at true I/O boundaries (e.g., network calls, AWS SDK clients, HTTP requests).
+- **Missing telemetry** — New features should include telemetry instrumentation. See `src/cli/telemetry/README.md` for
+  guidance on what and how to instrument.

AGENTS.md

@@ -143,6 +143,10 @@ See `docs/TESTING.md` for details.
 - Always look for existing types before creating a new type inline.
 - Re-usable constants must be defined in a constants file in the closest sensible subdirectory.
 
+## Telemetry
+
+New features must include telemetry instrumentation. See `src/cli/telemetry/README.md` for how to add metrics.
+
 ## Multi-Partition Support (GovCloud, China)
 
 The CLI supports multiple AWS partitions (commercial, GovCloud, China) through a central utility at

src/cli/telemetry/README.md

@@ -0,0 +1,160 @@
+# Adding New Telemetry Metrics
+
+## Overview
+
+Every CLI command emits a `command_run` metric with a command key, exit reason, and command-specific attributes. This
+guide shows how to add telemetry to a new command.
+
+## Step 1: Register the command in `schemas/command-run.ts`
+
+Add an entry to `COMMAND_SCHEMAS`. If the command has attributes, define a schema; otherwise use `NoAttrs`.
+
+```ts
+// No attributes (e.g. remove commands):
+'remove.widget': NoAttrs,
+
+// With attributes:
+const AddWidgetAttrs = safeSchema({
+  widget_type: WidgetType,   // must be z.enum(), z.boolean(), or z.number()
+  count: Count,
+});
+
+// Then register:
+'add.widget': AddWidgetAttrs,
+```
+
+**Rules:**
+
+- Only `z.enum()`, `z.boolean()`, `z.number()`, and `z.literal()` are allowed as field types (`safeSchema` enforces this
+  at compile time).
+- No `z.string()` — prevents PII leakage.
+
+## Step 2: Add any new enums to `schemas/common-shapes.ts`
+
+If your attributes need a new enum value:
+
+```ts
+export const WidgetType = z.enum(['basic', 'advanced']);
+```
+
+Export it so command handlers can import and use `standardize()` to normalize CLI input:
+
+```ts
+import { WidgetType, standardize } from '../telemetry/schemas/common-shapes.js';
+
+const type = standardize(WidgetType, userInput); // lowercases + validates
+```
+
+## Step 3: Instrument the command handler
+
+Pick the right helper from `cli-command-run.ts`:
+
+| Helper                                        | Use case                                          |
+| --------------------------------------------- | ------------------------------------------------- |
+| `runCliCommand(command, json, fn)`            | CLI handlers that print output and `process.exit` |
+| `withCommandRunTelemetry(command, attrs, fn)` | CLI/TUI handlers that return a `Result`           |
+| `withAddTelemetry(command, attrs, fn)`        | TUI hooks wrapping `.add()` calls                 |
+
+### CLI path — `runCliCommand`
+
+Wrap the command body. Throw on failure; return attrs on success.
+
+```ts
+import { runCliCommand } from '../telemetry/cli-command-run.js';
+
+await runCliCommand('remove.widget', !!options.json, async () => {
+  const result = await widgetPrimitive.remove(options.name);
+  if (!result.success) throw new Error(result.error);
+  console.log(JSON.stringify(result));
+  return {}; // attrs (NoAttrs → empty object)
+});
+```
+
+### CLI path with attributes — `runCliCommand`
+
+```ts
+import { runCliCommand } from '../telemetry/cli-command-run.js';
+import { WidgetType, standardize } from '../telemetry/schemas/common-shapes.js';
+
+await runCliCommand('add.widget', !!options.json, async () => {
+  const result = await widgetPrimitive.add(options);
+  if (!result.success) throw new Error(result.error);
+  console.log(JSON.stringify(result));
+  return {
+    widget_type: standardize(WidgetType, options.type),
+    count: options.items.length,
+  };
+});
+```
+
+### TUI path — `withCommandRunTelemetry`
+
+Returns the `Result` to the caller instead of exiting.
+
+```ts
+import { withCommandRunTelemetry } from '../telemetry/cli-command-run.js';
+
+const result = await withCommandRunTelemetry('remove.widget', {}, () => widgetPrimitive.remove(name));
+```
+
+### TUI path with attributes — `withAddTelemetry`
+
+```ts
+import { withAddTelemetry } from '../telemetry/cli-command-run.js';
+import { WidgetType, standardize } from '../telemetry/schemas/common-shapes.js';
+
+const result = await withAddTelemetry(
+  'add.widget',
+  { widget_type: standardize(WidgetType, config.type), count: config.items.length },
+  () => widgetPrimitive.add(config)
+);
+```
+
+## Concrete Example: `add.credential`
+
+1. **Schema** (`schemas/command-run.ts`):
+
+   ```ts
+   const AddCredentialAttrs = safeSchema({ credential_type: CredentialType });
+
+   export const COMMAND_SCHEMAS = {
+     'add.credential': AddCredentialAttrs,
+     // ...
+   };
+   ```
+
+2. **Enum** (`schemas/common-shapes.ts`):
+
+   ```ts
+   export const CredentialType = z.enum(['api-key', 'oauth']);
+   ```
+
+3. **CLI handler** (`primitives/CredentialPrimitive.tsx`):
+
+   ```ts
+   await runCliCommand('add.credential', !!cliOptions.json, async () => {
+     const result = await this.add(addOptions);
+     if (!result.success) throw new Error(result.error);
+     console.log(JSON.stringify(result));
+     return {
+       credential_type: standardize(CredentialType, cliOptions.type ?? 'api-key'),
+     };
+   });
+   ```
+
+4. **TUI hook** (`tui/hooks/useCreateCredential.ts`):
+   ```ts
+   const result = await withAddTelemetry(
+     'add.credential',
+     { credential_type: standardize(CredentialType, config.type) },
+     () => credentialPrimitive.add(config)
+   );
+   ```
+
+## Key Points
+
+- Telemetry never crashes the CLI — `standardize()` falls back gracefully, and `resilientParse` defaults invalid fields
+  to `'unknown'`.
+- The callback in `runCliCommand` must **throw** on failure (not return an error). The helper catches, records failure
+  telemetry, prints the error, and exits.
+- `withCommandRunTelemetry` and `withAddTelemetry` return the `Result` to the caller for further handling.