From 95a4639d90671ddbc8e1301749e16d60f259a1e6 Mon Sep 17 00:00:00 2001
From: ajmallesh <ajmallesh@gmail.com>
Date: Wed, 22 Oct 2025 16:16:36 -0700
Subject: [PATCH] docs: enhance export-metrics.js documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added comprehensive header comment explaining use case
- Documents data source (session.json from audit-logs)
- CSV output format and use cases clearly described
- Includes usage examples and note about raw data access
- Removes need for separate docs/ folder in repo

Docs were design artifacts, not needed in open source repo.
All relevant documentation now lives in code comments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/export-metrics.js | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/scripts/export-metrics.js b/scripts/export-metrics.js
index 17160cf..6b7e0c1 100755
--- a/scripts/export-metrics.js
+++ b/scripts/export-metrics.js
@@ -1,15 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Export Metrics Script
+ * Export Metrics to CSV
  *
- * Export session metrics from audit logs to CSV format for analysis.
+ * Converts session.json from audit-logs into CSV format for spreadsheet analysis.
  *
- * Use Cases:
- * - Performance analysis across sessions
- * - Cost tracking and budgeting
- * - Agent success rate analysis
- * - Benchmarking improvements
+ * DATA SOURCE:
+ * - Reads from: audit-logs/{hostname}_{sessionId}/session.json
+ * - Source of truth for all metrics, timing, and cost data
+ * - Automatically created by Shannon during agent execution
+ *
+ * CSV OUTPUT:
+ * - One row per agent with: agent, phase, status, attempts, duration_ms, cost_usd
+ * - Perfect for importing into Excel/Google Sheets for analysis
+ *
+ * USE CASES:
+ * - Compare performance across multiple sessions
+ * - Track costs and optimize budget
+ * - Identify slow agents for optimization
+ * - Generate charts and visualizations
+ * - Export data for external reporting tools
+ *
+ * EXAMPLES:
+ * ```bash
+ * # Export to stdout
+ * ./scripts/export-metrics.js --session-id abc123
+ *
+ * # Export to file
+ * ./scripts/export-metrics.js --session-id abc123 --output metrics.csv
+ *
+ * # Find session ID from Shannon store
+ * cat .shannon-store.json | jq '.sessions | keys'
+ * ```
+ *
+ * NOTE: For raw metrics, just read audit-logs/.../session.json directly.
+ * This script only exists to provide a spreadsheet-friendly CSV format.
  */
 
 import chalk from 'chalk';