@principal-ai/principal-view-cli 0.2.3 → 0.3.0

package/dist/commands/formats.js

@@ -181,100 +181,100 @@ ${chalk.bold('Validation:')}
 ${chalk.bold.cyan('Execution Format (.otel.json)')}
 ${chalk.dim('═'.repeat(70))}
 
-Execution files contain captured OTEL spans from test runs or production code.
-These files are exported by your test infrastructure and used for visualization
+Execution files use the ${chalk.bold('standard OTLP (OpenTelemetry Protocol) JSON format')}.
+These files are exported by OpenTelemetry SDK and used for visualization
 and validation against canvas schemas.
 
 ${chalk.bold('File Location:')}
   ${chalk.yellow('__executions__/')}${chalk.dim('<feature-name>.otel.json')}
-  ${chalk.dim('(auto-generated by test infrastructure)')}
+  ${chalk.dim('(auto-generated by test infrastructure with OpenTelemetry SDK)')}
 
 ${chalk.bold('IMPORTANT:')} __executions__/ directory must be committed to git!
 
-${chalk.bold('File Structure:')}
+${chalk.bold('File Structure (OTLP JSON Format):')}
 ${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
 ${chalk.dim('│')} {                                                                  ${chalk.dim('│')}
-${chalk.dim('│')}   ${chalk.green('"exportedAt"')}: "2025-01-21T10:30:00.000Z",  ${chalk.dim('// ISO timestamp')} ${chalk.dim('│')}
-${chalk.dim('│')}   ${chalk.green('"serviceName"')}: "my-service",               ${chalk.dim('// Service name')}  ${chalk.dim('│')}
-${chalk.dim('│')}   ${chalk.green('"spanCount"')}: 5,                            ${chalk.dim('// Total spans')}   ${chalk.dim('│')}
-${chalk.dim('│')}   ${chalk.green('"spans"')}: [                                                     ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"resourceSpans"')}: [                  ${chalk.dim('// OTLP root structure')}      ${chalk.dim('│')}
 ${chalk.dim('│')}     {                                                              ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"traceId"')}: "4bf92f3577b34da6...",  ${chalk.dim('// 32 hex chars')}     ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"spanId"')}: "00f067aa0ba902b7",     ${chalk.dim('// 16 hex chars')}     ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"parentSpanId"')}: "abc123...",      ${chalk.dim('// Parent span (null for root)')} ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"name"')}: "test:feature-name",     ${chalk.dim('// Span name')}         ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"kind"')}: "INTERNAL",              ${chalk.dim('// Span kind')}         ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"startTime"')}: 1703548800000,      ${chalk.dim('// Unix ms')}           ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"endTime"')}: 1703548800050,        ${chalk.dim('// Unix ms')}           ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"duration"')}: 50,                  ${chalk.dim('// Duration in ms')}    ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"attributes"')}: {                  ${chalk.dim('// Event attributes')}  ${chalk.dim('│')}
-${chalk.dim('│')}         "input.size": 42,                                        ${chalk.dim('│')}
-${chalk.dim('│')}         "output.success": true                                   ${chalk.dim('│')}
-${chalk.dim('│')}       },                                                          ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"status"')}: {                                                 ${chalk.dim('│')}
-${chalk.dim('│')}         "code": "OK"                    ${chalk.dim('// OK, ERROR, UNSET')}    ${chalk.dim('│')}
-${chalk.dim('│')}       },                                                          ${chalk.dim('│')}
-${chalk.dim('│')}       ${chalk.yellow('"events"')}: []                      ${chalk.dim('// Optional span events')}  ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"resource"')}: {                                                  ${chalk.dim('│')}
+${chalk.dim('│')}         ${chalk.cyan('"attributes"')}: [                                              ${chalk.dim('│')}
+${chalk.dim('│')}           { "key": "service.name", "value": { "stringValue": "..." }} ${chalk.dim('│')}
+${chalk.dim('│')}         ]                                                          ${chalk.dim('│')}
+${chalk.dim('│')}       },                                                            ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"scopeSpans"')}: [                                               ${chalk.dim('│')}
+${chalk.dim('│')}         {                                                          ${chalk.dim('│')}
+${chalk.dim('│')}           ${chalk.cyan('"scope"')}: { "name": "...", "version": "..." },           ${chalk.dim('│')}
+${chalk.dim('│')}           ${chalk.cyan('"spans"')}: [                                                ${chalk.dim('│')}
+${chalk.dim('│')}             {                                                      ${chalk.dim('│')}
+${chalk.dim('│')}               "traceId": "4bf92f3577b34da6...",  ${chalk.dim('// 32 hex chars')}   ${chalk.dim('│')}
+${chalk.dim('│')}               "spanId": "00f067aa0ba902b7",      ${chalk.dim('// 16 hex chars')}   ${chalk.dim('│')}
+${chalk.dim('│')}               "name": "test:feature-name",       ${chalk.dim('// Span name')}      ${chalk.dim('│')}
+${chalk.dim('│')}               "kind": 0,                         ${chalk.dim('// 0=INTERNAL')}     ${chalk.dim('│')}
+${chalk.dim('│')}               "startTimeUnixNano": "1703...",    ${chalk.dim('// Unix nanoseconds')} ${chalk.dim('│')}
+${chalk.dim('│')}               "endTimeUnixNano": "1703...",      ${chalk.dim('// Unix nanoseconds')} ${chalk.dim('│')}
+${chalk.dim('│')}               "attributes": [                    ${chalk.dim('// Key-value pairs')} ${chalk.dim('│')}
+${chalk.dim('│')}                 { "key": "input.size", "value": { "intValue": 42 } } ${chalk.dim('│')}
+${chalk.dim('│')}               ],                                                    ${chalk.dim('│')}
+${chalk.dim('│')}               "events": [                        ${chalk.dim('// Span events')}    ${chalk.dim('│')}
+${chalk.dim('│')}                 {                                                  ${chalk.dim('│')}
+${chalk.dim('│')}                   "timeUnixNano": "1703...",                      ${chalk.dim('│')}
+${chalk.dim('│')}                   "name": "validation.started",                   ${chalk.dim('│')}
+${chalk.dim('│')}                   "attributes": [...]                             ${chalk.dim('│')}
+${chalk.dim('│')}                 }                                                  ${chalk.dim('│')}
+${chalk.dim('│')}               ]                                                    ${chalk.dim('│')}
+${chalk.dim('│')}             }                                                      ${chalk.dim('│')}
+${chalk.dim('│')}           ]                                                        ${chalk.dim('│')}
+${chalk.dim('│')}         }                                                          ${chalk.dim('│')}
+${chalk.dim('│')}       ]                                                            ${chalk.dim('│')}
 ${chalk.dim('│')}     }                                                              ${chalk.dim('│')}
 ${chalk.dim('│')}   ]                                                                ${chalk.dim('│')}
 ${chalk.dim('│')} }                                                                  ${chalk.dim('│')}
 ${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
 
-${chalk.bold('Field Descriptions:')}
+${chalk.bold('OTLP Format Details:')}
 
-${chalk.cyan('exportedAt')} ${chalk.dim('(string, required)')}
-  ISO 8601 timestamp when the file was exported
+${chalk.cyan('resourceSpans')} ${chalk.dim('(array, required)')}
+  Root array containing resource-grouped spans
 
-${chalk.cyan('serviceName')} ${chalk.dim('(string, required)')}
-  Name of the service/test suite that generated these spans
+${chalk.cyan('resource.attributes')} ${chalk.dim('(array)')}
+  Metadata about the service (e.g., service.name)
 
-${chalk.cyan('spanCount')} ${chalk.dim('(number, required)')}
-  Total number of spans in this execution
+${chalk.cyan('scopeSpans')} ${chalk.dim('(array, required)')}
+  Instrumentation scope-grouped spans
 
 ${chalk.cyan('spans')} ${chalk.dim('(array, required)')}
-  Array of span objects containing OTEL trace data
-
-${chalk.bold('Span Object Fields:')}
-
-${chalk.cyan('traceId')} ${chalk.dim('(string, 32 hex chars)')}
-  Unique identifier for the entire trace
-
-${chalk.cyan('spanId')} ${chalk.dim('(string, 16 hex chars)')}
-  Unique identifier for this specific span
-
-${chalk.cyan('parentSpanId')} ${chalk.dim('(string | null)')}
-  Parent span ID, or null for root span
-
-${chalk.cyan('name')} ${chalk.dim('(string)')}
-  Descriptive name for the operation
-
-${chalk.cyan('kind')} ${chalk.dim('(string)')}
-  Span kind: INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER
-
-${chalk.cyan('startTime')} ${chalk.dim('(number)')}
-  Unix timestamp in milliseconds when span started
-
-${chalk.cyan('endTime')} ${chalk.dim('(number)')}
-  Unix timestamp in milliseconds when span ended
-
-${chalk.cyan('duration')} ${chalk.dim('(number)')}
-  Duration in milliseconds (endTime - startTime)
-
-${chalk.cyan('attributes')} ${chalk.dim('(object)')}
-  Key-value pairs of event attributes (validated against canvas schema)
-
-${chalk.cyan('status')} ${chalk.dim('(object)')}
-  Status code (OK, ERROR, UNSET) and optional message
-
-${chalk.cyan('events')} ${chalk.dim('(array)')}
-  Optional array of timestamped events within the span
+  Array of span objects with OTLP structure
+
+${chalk.bold('Span Fields (OTLP Standard):')}
+
+${chalk.cyan('traceId')} ${chalk.dim('(string)')} - Unique trace identifier (32 hex chars)
+${chalk.cyan('spanId')} ${chalk.dim('(string)')} - Unique span identifier (16 hex chars)
+${chalk.cyan('parentSpanId')} ${chalk.dim('(string, optional)')} - Parent span ID
+${chalk.cyan('name')} ${chalk.dim('(string)')} - Operation name
+${chalk.cyan('kind')} ${chalk.dim('(number)')} - 0=UNSPECIFIED, 1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER
+${chalk.cyan('startTimeUnixNano')} ${chalk.dim('(string)')} - Start time in Unix nanoseconds
+${chalk.cyan('endTimeUnixNano')} ${chalk.dim('(string)')} - End time in Unix nanoseconds
+${chalk.cyan('attributes')} ${chalk.dim('(array)')} - Key-value pairs: [{ key, value: { stringValue|intValue|... } }]
+${chalk.cyan('events')} ${chalk.dim('(array)')} - Span events with timestamps and attributes
+${chalk.cyan('status')} ${chalk.dim('(object)')} - Status: { code: 1=OK, 2=ERROR }
+
+${chalk.bold('Attribute Value Format:')}
+  { "stringValue": "..." }  ${chalk.dim('// For strings')}
+  { "intValue": 42 }        ${chalk.dim('// For integers')}
+  { "doubleValue": 3.14 }   ${chalk.dim('// For floats')}
+  { "boolValue": true }     ${chalk.dim('// For booleans')}
 
 ${chalk.bold('Generation:')}
-  Set up test infrastructure with OTEL exporters that write to __executions__/
-  See: docs/guides/adding-opentelemetry-to-tests.md
+  Use OpenTelemetry SDK with OTLP JSON exporter
+  Example: @opentelemetry/sdk-trace-node + InMemorySpanExporter
+  See: tests/otel-setup.ts in the add-skill repository
 
 ${chalk.bold('Validation:')}
   ${chalk.cyan('npx @principal-ai/principal-view-cli validate-execution <file>')}
+
+${chalk.bold('Resources:')}
+  OTLP Spec: https://opentelemetry.io/docs/specs/otlp/
+  OpenTelemetry JS: https://github.com/open-telemetry/opentelemetry-js
 `,
     examples: `
 ${chalk.bold.cyan('Complete File Examples')}

package/dist/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+pCpC,wBAAgB,qBAAqB,IAAI,OAAO,CAiI/C"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0sCpC,wBAAgB,qBAAqB,IAAI,OAAO,CAiI/C"}

package/dist/commands/validate.js

@@ -225,7 +225,7 @@ const ALLOWED_CANVAS_FIELDS = {
         'name',
         'description',
         'otel',
-        'events',
+        'event',
         'shape',
         'icon',
         'fill',
@@ -346,7 +346,7 @@ function findSimilarField(field, allowedFields) {
  * Check if a canvas has OTEL-related features
  * Returns true if the canvas contains any of:
  * 1. Nodes with pv.otel extension (kind, category)
- * 2. Event schemas (pv.events with validation)
+ * 2. Event schema (pv.event with validation)
  * 3. Canvas scope/audit config (OTEL log routing)
  * 4. Resource matching for OTEL logs
  */
@@ -373,8 +373,8 @@ function hasOtelFeatures(canvas) {
                     if (nodePv.otel !== undefined) {
                         return true;
                     }
-                    // Check for event schemas (pv.events)
-                    if (nodePv.events !== undefined) {
+                    // Check for event schema (pv.event)
+                    if (nodePv.event !== undefined) {
                         return true;
                     }
                     // Check for resourceMatch (OTEL log routing)
@@ -634,8 +634,19 @@ function validateCanvas(canvas, filePath, library, repositoryPath) {
                 if (nodePv.otel && typeof nodePv.otel === 'object') {
                     checkUnknownFields(nodePv.otel, ALLOWED_CANVAS_FIELDS.nodePvOtel, `${nodePath}.pv.otel`, issues);
                 }
+                // For .otel.canvas files: require event field on nodes with pv extension (except groups)
+                if (filePath.endsWith('.otel.canvas') && nodeType !== 'group') {
+                    if (nodePv.event === undefined) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" in .otel.canvas file must have "pv.event" field`,
+                            path: `${nodePath}.pv.event`,
+                            suggestion: 'Add event name, e.g.: "event": "user.login" or "event": "order.created"',
+                        });
+                    }
+                }
                 // Validate source file references for OTEL event nodes
-                const hasOtelFeatures = nodePv.otel !== undefined || nodePv.events !== undefined;
+                const hasOtelFeatures = nodePv.otel !== undefined || nodePv.event !== undefined;
                 if (hasOtelFeatures) {
                     // OTEL nodes must have at least one source file reference
                     if (!Array.isArray(nodePv.sources) || nodePv.sources.length === 0) {
@@ -646,22 +657,50 @@ function validateCanvas(canvas, filePath, library, repositoryPath) {
                             suggestion: 'Add at least one source file reference, e.g.: "sources": ["src/services/MyService.ts"]',
                         });
                     }
+                    // For .otel.canvas files: nodes with event must have pv.otel for UI rendering
+                    if (filePath.endsWith('.otel.canvas') && nodePv.event !== undefined && nodePv.otel === undefined) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" in .otel.canvas file has event but is missing "pv.otel" field required for UI badges`,
+                            path: `${nodePath}.pv.otel`,
+                            suggestion: 'Add OTEL metadata for UI rendering, e.g.: "otel": { "kind": "event", "category": "lifecycle", "isNew": true }',
+                        });
+                    }
                 }
-                // Validate that all source files exist (if repository path is provided)
-                if (Array.isArray(nodePv.sources) && repositoryPath) {
+                // Validate source file paths
+                if (Array.isArray(nodePv.sources)) {
                     nodePv.sources.forEach((source, sourceIndex) => {
                         if (typeof source === 'string') {
-                            // Remove glob patterns (* characters) to get the base path
-                            const cleanPath = source.replace(/\*/g, '');
-                            const fullPath = resolve(repositoryPath, cleanPath);
-                            if (!existsSync(fullPath)) {
+                            // Check for glob patterns
+                            if (/[*?[\]{}]/.test(source)) {
                                 issues.push({
                                     type: 'error',
-                                    message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                                    message: `Node "${nodeLabel}" has glob pattern in sources: ${source}`,
                                     path: `${nodePath}.pv.sources[${sourceIndex}]`,
-                                    suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`,
+                                    suggestion: 'Use exact file paths only. Glob patterns (*, ?, [], {}) are not supported in sources.',
                                 });
                             }
+                            // Check for line number suffix (e.g., "file.ts:123")
+                            if (/:\d+$/.test(source)) {
+                                issues.push({
+                                    type: 'error',
+                                    message: `Node "${nodeLabel}" has line number suffix in sources: ${source}`,
+                                    path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                    suggestion: 'Remove line number suffix. Use exact file paths only (e.g., "src/file.ts" not "src/file.ts:123").',
+                                });
+                            }
+                            // Validate that source file exists (if repository path is provided)
+                            if (repositoryPath) {
+                                const fullPath = resolve(repositoryPath, source);
+                                if (!existsSync(fullPath)) {
+                                    issues.push({
+                                        type: 'error',
+                                        message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                                        path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                        suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`,
+                                    });
+                                }
+                            }
                         }
                     });
                 }

package/dist/index.cjs

@@ -228612,7 +228612,7 @@ var ALLOWED_CANVAS_FIELDS = {
     "name",
     "description",
     "otel",
-    "events",
+    "event",
     "shape",
     "icon",
     "fill",
@@ -228735,7 +228735,7 @@ function hasOtelFeatures(canvas) {
           if (nodePv.otel !== void 0) {
             return true;
           }
-          if (nodePv.events !== void 0) {
+          if (nodePv.event !== void 0) {
             return true;
           }
           if (nodePv.resourceMatch !== void 0) {
@@ -229019,7 +229019,17 @@ function validateCanvas(canvas, filePath, library, repositoryPath) {
             issues
           );
         }
-        const hasOtelFeatures2 = nodePv.otel !== void 0 || nodePv.events !== void 0;
+        if (filePath.endsWith(".otel.canvas") && nodeType !== "group") {
+          if (nodePv.event === void 0) {
+            issues.push({
+              type: "error",
+              message: `Node "${nodeLabel}" in .otel.canvas file must have "pv.event" field`,
+              path: `${nodePath2}.pv.event`,
+              suggestion: 'Add event name, e.g.: "event": "user.login" or "event": "order.created"'
+            });
+          }
+        }
+        const hasOtelFeatures2 = nodePv.otel !== void 0 || nodePv.event !== void 0;
         if (hasOtelFeatures2) {
           if (!Array.isArray(nodePv.sources) || nodePv.sources.length === 0) {
             issues.push({
@@ -229029,20 +229039,45 @@ function validateCanvas(canvas, filePath, library, repositoryPath) {
               suggestion: 'Add at least one source file reference, e.g.: "sources": ["src/services/MyService.ts"]'
             });
           }
+          if (filePath.endsWith(".otel.canvas") && nodePv.event !== void 0 && nodePv.otel === void 0) {
+            issues.push({
+              type: "error",
+              message: `Node "${nodeLabel}" in .otel.canvas file has event but is missing "pv.otel" field required for UI badges`,
+              path: `${nodePath2}.pv.otel`,
+              suggestion: 'Add OTEL metadata for UI rendering, e.g.: "otel": { "kind": "event", "category": "lifecycle", "isNew": true }'
+            });
+          }
         }
-        if (Array.isArray(nodePv.sources) && repositoryPath) {
+        if (Array.isArray(nodePv.sources)) {
           nodePv.sources.forEach((source, sourceIndex) => {
             if (typeof source === "string") {
-              const cleanPath = source.replace(/\*/g, "");
-              const fullPath = (0, import_node_path5.resolve)(repositoryPath, cleanPath);
-              if (!(0, import_node_fs4.existsSync)(fullPath)) {
+              if (/[*?[\]{}]/.test(source)) {
+                issues.push({
+                  type: "error",
+                  message: `Node "${nodeLabel}" has glob pattern in sources: ${source}`,
+                  path: `${nodePath2}.pv.sources[${sourceIndex}]`,
+                  suggestion: "Use exact file paths only. Glob patterns (*, ?, [], {}) are not supported in sources."
+                });
+              }
+              if (/:\d+$/.test(source)) {
                 issues.push({
                   type: "error",
-                  message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                  message: `Node "${nodeLabel}" has line number suffix in sources: ${source}`,
                   path: `${nodePath2}.pv.sources[${sourceIndex}]`,
-                  suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`
+                  suggestion: 'Remove line number suffix. Use exact file paths only (e.g., "src/file.ts" not "src/file.ts:123").'
                 });
               }
+              if (repositoryPath) {
+                const fullPath = (0, import_node_path5.resolve)(repositoryPath, source);
+                if (!(0, import_node_fs4.existsSync)(fullPath)) {
+                  issues.push({
+                    type: "error",
+                    message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                    path: `${nodePath2}.pv.sources[${sourceIndex}]`,
+                    suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`
+                  });
+                }
+              }
             }
           });
         }
@@ -241290,100 +241325,100 @@ ${source_default.bold("Validation:")}
 ${source_default.bold.cyan("Execution Format (.otel.json)")}
 ${source_default.dim("\u2550".repeat(70))}
 
-Execution files contain captured OTEL spans from test runs or production code.
-These files are exported by your test infrastructure and used for visualization
+Execution files use the ${source_default.bold("standard OTLP (OpenTelemetry Protocol) JSON format")}.
+These files are exported by OpenTelemetry SDK and used for visualization
 and validation against canvas schemas.
 
 ${source_default.bold("File Location:")}
   ${source_default.yellow("__executions__/")}${source_default.dim("<feature-name>.otel.json")}
-  ${source_default.dim("(auto-generated by test infrastructure)")}
+  ${source_default.dim("(auto-generated by test infrastructure with OpenTelemetry SDK)")}
 
 ${source_default.bold("IMPORTANT:")} __executions__/ directory must be committed to git!
 
-${source_default.bold("File Structure:")}
+${source_default.bold("File Structure (OTLP JSON Format):")}
 ${source_default.dim("\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510")}
 ${source_default.dim("\u2502")} {                                                                  ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}   ${source_default.green('"exportedAt"')}: "2025-01-21T10:30:00.000Z",  ${source_default.dim("// ISO timestamp")} ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}   ${source_default.green('"serviceName"')}: "my-service",               ${source_default.dim("// Service name")}  ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}   ${source_default.green('"spanCount"')}: 5,                            ${source_default.dim("// Total spans")}   ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}   ${source_default.green('"spans"')}: [                                                     ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}   ${source_default.green('"resourceSpans"')}: [                  ${source_default.dim("// OTLP root structure")}      ${source_default.dim("\u2502")}
 ${source_default.dim("\u2502")}     {                                                              ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"traceId"')}: "4bf92f3577b34da6...",  ${source_default.dim("// 32 hex chars")}     ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"spanId"')}: "00f067aa0ba902b7",     ${source_default.dim("// 16 hex chars")}     ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"parentSpanId"')}: "abc123...",      ${source_default.dim("// Parent span (null for root)")} ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"name"')}: "test:feature-name",     ${source_default.dim("// Span name")}         ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"kind"')}: "INTERNAL",              ${source_default.dim("// Span kind")}         ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"startTime"')}: 1703548800000,      ${source_default.dim("// Unix ms")}           ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"endTime"')}: 1703548800050,        ${source_default.dim("// Unix ms")}           ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"duration"')}: 50,                  ${source_default.dim("// Duration in ms")}    ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"attributes"')}: {                  ${source_default.dim("// Event attributes")}  ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}         "input.size": 42,                                        ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}         "output.success": true                                   ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       },                                                          ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"status"')}: {                                                 ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}         "code": "OK"                    ${source_default.dim("// OK, ERROR, UNSET")}    ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       },                                                          ${source_default.dim("\u2502")}
-${source_default.dim("\u2502")}       ${source_default.yellow('"events"')}: []                      ${source_default.dim("// Optional span events")}  ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"resource"')}: {                                                  ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         ${source_default.cyan('"attributes"')}: [                                              ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           { "key": "service.name", "value": { "stringValue": "..." }} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         ]                                                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       },                                                            ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"scopeSpans"')}: [                                               ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         {                                                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           ${source_default.cyan('"scope"')}: { "name": "...", "version": "..." },           ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           ${source_default.cyan('"spans"')}: [                                                ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}             {                                                      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "traceId": "4bf92f3577b34da6...",  ${source_default.dim("// 32 hex chars")}   ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "spanId": "00f067aa0ba902b7",      ${source_default.dim("// 16 hex chars")}   ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "name": "test:feature-name",       ${source_default.dim("// Span name")}      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "kind": 0,                         ${source_default.dim("// 0=INTERNAL")}     ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "startTimeUnixNano": "1703...",    ${source_default.dim("// Unix nanoseconds")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "endTimeUnixNano": "1703...",      ${source_default.dim("// Unix nanoseconds")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "attributes": [                    ${source_default.dim("// Key-value pairs")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                 { "key": "input.size", "value": { "intValue": 42 } } ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               ],                                                    ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               "events": [                        ${source_default.dim("// Span events")}    ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                 {                                                  ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                   "timeUnixNano": "1703...",                      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                   "name": "validation.started",                   ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                   "attributes": [...]                             ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}                 }                                                  ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}               ]                                                    ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}             }                                                      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           ]                                                        ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         }                                                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ]                                                            ${source_default.dim("\u2502")}
 ${source_default.dim("\u2502")}     }                                                              ${source_default.dim("\u2502")}
 ${source_default.dim("\u2502")}   ]                                                                ${source_default.dim("\u2502")}
 ${source_default.dim("\u2502")} }                                                                  ${source_default.dim("\u2502")}
 ${source_default.dim("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518")}
 
-${source_default.bold("Field Descriptions:")}
+${source_default.bold("OTLP Format Details:")}
 
-${source_default.cyan("exportedAt")} ${source_default.dim("(string, required)")}
-  ISO 8601 timestamp when the file was exported
+${source_default.cyan("resourceSpans")} ${source_default.dim("(array, required)")}
+  Root array containing resource-grouped spans
 
-${source_default.cyan("serviceName")} ${source_default.dim("(string, required)")}
-  Name of the service/test suite that generated these spans
+${source_default.cyan("resource.attributes")} ${source_default.dim("(array)")}
+  Metadata about the service (e.g., service.name)
 
-${source_default.cyan("spanCount")} ${source_default.dim("(number, required)")}
-  Total number of spans in this execution
+${source_default.cyan("scopeSpans")} ${source_default.dim("(array, required)")}
+  Instrumentation scope-grouped spans
 
 ${source_default.cyan("spans")} ${source_default.dim("(array, required)")}
-  Array of span objects containing OTEL trace data
-
-${source_default.bold("Span Object Fields:")}
-
-${source_default.cyan("traceId")} ${source_default.dim("(string, 32 hex chars)")}
-  Unique identifier for the entire trace
-
-${source_default.cyan("spanId")} ${source_default.dim("(string, 16 hex chars)")}
-  Unique identifier for this specific span
+  Array of span objects with OTLP structure
 
-${source_default.cyan("parentSpanId")} ${source_default.dim("(string | null)")}
-  Parent span ID, or null for root span
+${source_default.bold("Span Fields (OTLP Standard):")}
 
-${source_default.cyan("name")} ${source_default.dim("(string)")}
-  Descriptive name for the operation
+${source_default.cyan("traceId")} ${source_default.dim("(string)")} - Unique trace identifier (32 hex chars)
+${source_default.cyan("spanId")} ${source_default.dim("(string)")} - Unique span identifier (16 hex chars)
+${source_default.cyan("parentSpanId")} ${source_default.dim("(string, optional)")} - Parent span ID
+${source_default.cyan("name")} ${source_default.dim("(string)")} - Operation name
+${source_default.cyan("kind")} ${source_default.dim("(number)")} - 0=UNSPECIFIED, 1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER
+${source_default.cyan("startTimeUnixNano")} ${source_default.dim("(string)")} - Start time in Unix nanoseconds
+${source_default.cyan("endTimeUnixNano")} ${source_default.dim("(string)")} - End time in Unix nanoseconds
+${source_default.cyan("attributes")} ${source_default.dim("(array)")} - Key-value pairs: [{ key, value: { stringValue|intValue|... } }]
+${source_default.cyan("events")} ${source_default.dim("(array)")} - Span events with timestamps and attributes
+${source_default.cyan("status")} ${source_default.dim("(object)")} - Status: { code: 1=OK, 2=ERROR }
 
-${source_default.cyan("kind")} ${source_default.dim("(string)")}
-  Span kind: INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER
-
-${source_default.cyan("startTime")} ${source_default.dim("(number)")}
-  Unix timestamp in milliseconds when span started
-
-${source_default.cyan("endTime")} ${source_default.dim("(number)")}
-  Unix timestamp in milliseconds when span ended
-
-${source_default.cyan("duration")} ${source_default.dim("(number)")}
-  Duration in milliseconds (endTime - startTime)
-
-${source_default.cyan("attributes")} ${source_default.dim("(object)")}
-  Key-value pairs of event attributes (validated against canvas schema)
-
-${source_default.cyan("status")} ${source_default.dim("(object)")}
-  Status code (OK, ERROR, UNSET) and optional message
-
-${source_default.cyan("events")} ${source_default.dim("(array)")}
-  Optional array of timestamped events within the span
+${source_default.bold("Attribute Value Format:")}
+  { "stringValue": "..." }  ${source_default.dim("// For strings")}
+  { "intValue": 42 }        ${source_default.dim("// For integers")}
+  { "doubleValue": 3.14 }   ${source_default.dim("// For floats")}
+  { "boolValue": true }     ${source_default.dim("// For booleans")}
 
 ${source_default.bold("Generation:")}
-  Set up test infrastructure with OTEL exporters that write to __executions__/
-  See: docs/guides/adding-opentelemetry-to-tests.md
+  Use OpenTelemetry SDK with OTLP JSON exporter
+  Example: @opentelemetry/sdk-trace-node + InMemorySpanExporter
+  See: tests/otel-setup.ts in the add-skill repository
 
 ${source_default.bold("Validation:")}
   ${source_default.cyan("npx @principal-ai/principal-view-cli validate-execution <file>")}
+
+${source_default.bold("Resources:")}
+  OTLP Spec: https://opentelemetry.io/docs/specs/otlp/
+  OpenTelemetry JS: https://github.com/open-telemetry/opentelemetry-js
 `,
   examples: `
 ${source_default.bold.cyan("Complete File Examples")}