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,74 @@
+# 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`:
+
+```ts
+// No attributes:
+'remove.widget': NoAttrs,
+
+// With attributes:
+'add.widget': safeSchema({
+  widget_type: WidgetType,   // z.enum(), z.boolean(), z.number(), or z.literal() only
+  count: Count,
+}),
+```
+
+`safeSchema` enforces allowed field types at compile time. No `z.string()` fields.
+
+## Step 2: Add enums to `schemas/common-shapes.ts`
+
+```ts
+export const WidgetType = z.enum(['basic', 'advanced']);
+```
+
+Use `standardize()` to normalize input before recording:
+
+```ts
+import { WidgetType, standardize } from '../telemetry/schemas/common-shapes.js';
+
+const type = standardize(WidgetType, userInput);
+```
+
+## Step 3: Instrument the command handler
+
+| Helper                                        | Use case                            |
+| --------------------------------------------- | ----------------------------------- |
+| `runCliCommand(command, json, fn)`            | CLI handlers that `process.exit`    |
+| `withCommandRunTelemetry(command, attrs, fn)` | CLI/TUI handlers returning `Result` |
+| `withAddTelemetry(command, attrs, fn)`        | TUI hooks wrapping `.add()` calls   |
+
+**`runCliCommand`** — throw on failure, return attrs on success:
+
+```ts
+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 };
+});
+```
+
+**`withCommandRunTelemetry`** / **`withAddTelemetry`** — returns `Result` to caller:
+
+```ts
+const result = await withAddTelemetry(
+  'add.widget',
+  { widget_type: standardize(WidgetType, config.type), count: config.items.length },
+  () => widgetPrimitive.add(config)
+);
+```
+
+## Key Points
+
+- Telemetry never crashes the CLI — `standardize()` falls back gracefully, `resilientParse` defaults invalid fields to
+  `'unknown'`.
+- `runCliCommand` callback must **throw** on failure. The helper catches, records failure telemetry, prints the error,
+  and exits.
+- `withCommandRunTelemetry` and `withAddTelemetry` return the `Result` for further handling.