@principal-ai/principal-view-cli 0.2.2 → 0.2.4

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,6 +229039,14 @@ 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) {
           nodePv.sources.forEach((source, sourceIndex) => {
@@ -241111,6 +241129,478 @@ function createSchemaCommand() {
   return command;
 }
 
+// src/commands/formats.ts
+var FORMAT_SECTIONS = {
+  overview: `
+${source_default.bold.cyan("Principal View OTEL File Formats")}
+${source_default.dim("\u2550".repeat(70))}
+
+The Principal View OTEL workflow uses three main file types:
+
+${source_default.bold("1. Canvas Files")} ${source_default.yellow(".otel.canvas")}
+   Define OTEL event schemas and telemetry structure for a feature.
+   These are the single source of truth for what events should be emitted.
+
+${source_default.bold("2. Narrative Files")} ${source_default.yellow(".narrative.json")}
+   Define scenarios and templates for rendering executions as human-readable
+   narratives based on the emitted events.
+
+${source_default.bold("3. Execution Files")} ${source_default.yellow(".otel.json")}
+   Captured OTEL spans from test runs or production code, exported for
+   visualization and validation against canvas schemas.
+
+Run ${source_default.cyan("npx @principal-ai/principal-view-cli formats <section>")} for details on:
+  ${source_default.yellow("canvas")}       .otel.canvas format and event schemas
+  ${source_default.yellow("narrative")}    .narrative.json format and scenario structure
+  ${source_default.yellow("execution")}    .otel.json format for captured spans
+  ${source_default.yellow("examples")}     Complete example files
+`,
+  canvas: `
+${source_default.bold.cyan("Canvas Format (.otel.canvas)")}
+${source_default.dim("\u2550".repeat(70))}
+
+Canvas files define the OTEL event schemas for a feature. They document what
+events should be emitted and what attributes each event must/may contain.
+
+${source_default.bold("File Location:")}
+  ${source_default.dim(".principal-views/")}${source_default.yellow("<feature-name>.otel.canvas")}
+
+${source_default.bold("Required Structure:")}
+${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('"nodes"')}: [                  ${source_default.dim("// Array of event schemas")}      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}     {                                                              ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"id"')}: "event-id",      ${source_default.dim("// Unique identifier")}         ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"type"')}: "text",                                              ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"text"')}: "# Event Name", ${source_default.dim("// Markdown description")}     ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"x"')}: 0, ${source_default.yellow('"y"')}: 0, ${source_default.yellow('"width"')}: 200, ${source_default.yellow('"height"')}: 100,                   ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.green('"pv"')}: {                                                        ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         ${source_default.cyan('"otelEvent"')}: {          ${source_default.dim("// OTEL event definition")}    ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           ${source_default.yellow('"name"')}: "feature.event.name",                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           ${source_default.cyan('"attributes"')}: {       ${source_default.dim("// Required & optional attrs")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}             ${source_default.green('"required"')}: ["attr.name", ...],                     ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}             ${source_default.green('"optional"')}: ["attr.name", ...]                      ${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.green('"edges"')}: [],                ${source_default.dim("// Optional: event relationships")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}   ${source_default.green('"pv"')}: {                                                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}     ${source_default.yellow('"name"')}: "Feature Name",  ${source_default.dim('// Feature name (NOT "...Canvas")')} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}     ${source_default.yellow('"version"')}: "1.0.0"                                            ${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("Event Schema Best Practices:")}
+
+${source_default.cyan("1. Canvas represents complete, encompassing functionality:")}
+   \u2705 API route - Full request/response cycle
+   \u2705 CLI command - Complete tool execution
+   \u2705 Business operation - End-to-end workflow
+   \u274C Individual helper functions (too granular)
+
+${source_default.cyan("2. Event naming convention:")}
+   ${source_default.yellow("<feature>.<operation>.<state>")}
+   Examples:
+   - validation.started
+   - validation.complete
+   - validation.error
+   - import.parsing.complete
+
+${source_default.cyan("3. Start simple (2-4 events):")}
+   - ${source_default.green("started")}  - When feature begins
+   - ${source_default.green("complete")} - When feature succeeds
+   - ${source_default.green("error")}    - When feature fails
+   - (optional) progress events for clear intermediate steps
+
+${source_default.cyan("4. Attribute naming conventions:")}
+   ${source_default.yellow("<category>.<name>")}
+   - input.*     (input.size, input.recordCount)
+   - output.*    (output.count, output.success)
+   - result.*    (result.validCount, result.invalidCount)
+   - error.*     (error.type, error.message, error.stage)
+   - duration.*  (duration.ms)
+
+${source_default.cyan("5. Required vs Optional attributes:")}
+   - ${source_default.green("required")}: Essential data needed for validation
+   - ${source_default.yellow("optional")}: Nice-to-have context, won't fail validation if missing
+
+${source_default.bold("Validation:")}
+  ${source_default.cyan("npx @principal-ai/principal-view-cli validate")}
+`,
+  narrative: `
+${source_default.bold.cyan("Narrative Format (.narrative.json)")}
+${source_default.dim("\u2550".repeat(70))}
+
+Narrative files define scenarios for rendering execution data as human-readable
+stories. They evaluate conditions against captured events to select the best
+matching narrative template.
+
+${source_default.bold("File Location:")}
+  ${source_default.dim(".principal-views/")}${source_default.yellow("<feature-name>.narrative.json")}
+  ${source_default.dim("(co-located with corresponding .otel.canvas file)")}
+
+${source_default.bold("Required Structure:")}
+${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('"name"')}: "Feature Name",      ${source_default.dim('// NOT "Feature Name Narratives"')} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}   ${source_default.green('"description"')}: "What the feature does",  ${source_default.dim('// Purpose, not "Narratives for..."')} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}   ${source_default.green('"scenarios"')}: [                                                 ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}     {                                                              ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"priority"')}: 1,           ${source_default.dim("// Lower = higher priority")}   ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"condition"')}: "...",      ${source_default.dim("// JSONPath/logic expression")} ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}       ${source_default.yellow('"template"')}: {            ${source_default.dim("// Narrative template")}        ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         ${source_default.cyan('"summary"')}: "...",    ${source_default.dim("// One-line summary")}          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}         ${source_default.cyan('"details"')}: [        ${source_default.dim("// Step-by-step details")}      ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           "Step 1: ...",                                          ${source_default.dim("\u2502")}
+${source_default.dim("\u2502")}           "Step 2: ...",                                          ${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("Naming Guidelines:")}
+
+  \u274C DON'T append "Narratives" to the name:
+     "name": "Package Processor Narratives"
+
+  \u2705 DO use the feature name directly:
+     "name": "Package Processor"
+
+  \u274C DON'T prefix description with boilerplate:
+     "description": "Human-readable narratives for package extraction..."
+
+  \u2705 DO describe the feature's purpose:
+     "description": "Package extraction and analysis from repository file trees"
+
+${source_default.bold("Scenario Best Practices:")}
+
+${source_default.cyan("1. Priority ordering (scenarios evaluated in order):")}
+   - ${source_default.green("1-10")}    Specific scenarios (success/failure cases)
+   - ${source_default.yellow("999")}     Fallback scenario (catches anything)
+
+${source_default.cyan("2. Standard scenario set:")}
+   - ${source_default.green("Success")} (priority 1): Feature completed successfully
+   - ${source_default.yellow("Failure")} (priority 2): Feature encountered error
+   - ${source_default.dim("Fallback")} (priority 999): Generic execution captured
+
+${source_default.cyan("3. Template interpolation:")}
+   Use {{path.to.value}} to reference event attributes
+   Examples:
+   - {{record.count}}
+   - {{error.message}}
+   - {{result.invalidCount}}
+
+${source_default.cyan("4. Template style:")}
+   - Clear, concise summary line
+   - 3-5 detail steps showing workflow
+   - Use emojis for visual scanning (\u2705 \u274C \u{1F4CB})
+   - Include key metrics and IDs
+
+${source_default.bold("Validation:")}
+  ${source_default.cyan("npx @principal-ai/principal-view-cli narrative validate")}
+`,
+  execution: `
+${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
+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.bold("IMPORTANT:")} __executions__/ directory must be committed to git!
+
+${source_default.bold("File Structure:")}
+${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.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.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.cyan("exportedAt")} ${source_default.dim("(string, required)")}
+  ISO 8601 timestamp when the file was exported
+
+${source_default.cyan("serviceName")} ${source_default.dim("(string, required)")}
+  Name of the service/test suite that generated these spans
+
+${source_default.cyan("spanCount")} ${source_default.dim("(number, required)")}
+  Total number of spans in this execution
+
+${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
+
+${source_default.cyan("parentSpanId")} ${source_default.dim("(string | null)")}
+  Parent span ID, or null for root span
+
+${source_default.cyan("name")} ${source_default.dim("(string)")}
+  Descriptive name for the operation
+
+${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("Generation:")}
+  Set up test infrastructure with OTEL exporters that write to __executions__/
+  See: docs/guides/adding-opentelemetry-to-tests.md
+
+${source_default.bold("Validation:")}
+  ${source_default.cyan("npx @principal-ai/principal-view-cli validate-execution <file>")}
+`,
+  examples: `
+${source_default.bold.cyan("Complete File Examples")}
+${source_default.dim("\u2550".repeat(70))}
+
+${source_default.bold("Example 1: Data Validator Canvas")}
+${source_default.dim("\u2500".repeat(70))}
+${source_default.yellow(".principal-views/data-validator.otel.canvas")}
+
+{
+  "nodes": [
+    {
+      "id": "validation-started",
+      "type": "text",
+      "text": "# validation.started\\n\\nEmitted when validation begins",
+      "x": 0, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.started",
+          "attributes": {
+            "required": ["input.recordCount"],
+            "optional": ["input.source"]
+          }
+        }
+      }
+    },
+    {
+      "id": "validation-complete",
+      "type": "text",
+      "text": "# validation.complete\\n\\nEmitted when validation succeeds",
+      "x": 250, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.complete",
+          "attributes": {
+            "required": ["result.validCount", "result.invalidCount"],
+            "optional": ["duration.ms"]
+          }
+        }
+      }
+    },
+    {
+      "id": "validation-error",
+      "type": "text",
+      "text": "# validation.error\\n\\nEmitted when validation fails",
+      "x": 500, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.error",
+          "attributes": {
+            "required": ["error.type", "error.message"],
+            "optional": ["error.stage"]
+          }
+        }
+      }
+    }
+  ],
+  "edges": [],
+  "pv": {
+    "name": "Data Validator",
+    "version": "1.0.0"
+  }
+}
+
+${source_default.bold("Example 2: Narrative Scenarios")}
+${source_default.dim("\u2500".repeat(70))}
+${source_default.yellow(".principal-views/data-validator.narrative.json")}
+
+{
+  "name": "Data Validator",
+  "description": "Validates data records against defined schemas",
+  "scenarios": [
+    {
+      "priority": 1,
+      "condition": "events[?name=='validation.complete']",
+      "template": {
+        "summary": "\u2705 Validated {{result.validCount}} records successfully",
+        "details": [
+          "\u{1F50D} Started validation",
+          "\u{1F4CA} Processed {{input.recordCount}} records",
+          "\u2705 {{result.validCount}} valid",
+          "\u274C {{result.invalidCount}} invalid"
+        ]
+      }
+    },
+    {
+      "priority": 2,
+      "condition": "events[?name=='validation.error']",
+      "template": {
+        "summary": "\u274C Validation failed: {{error.message}}",
+        "details": [
+          "\u{1F50D} Started validation",
+          "\u{1F4A5} Error occurred: {{error.message}}",
+          "\u{1F3F7}\uFE0F  Error type: {{error.type}}"
+        ]
+      }
+    },
+    {
+      "priority": 999,
+      "condition": "true",
+      "template": {
+        "summary": "\u{1F4CB} Validation execution captured",
+        "details": [
+          "\u{1F4E6} Captured {{spans.length}} events",
+          "\u23F1\uFE0F  Duration: {{duration.ms}}ms"
+        ]
+      }
+    }
+  ]
+}
+
+${source_default.bold("Example 3: Execution File")}
+${source_default.dim("\u2500".repeat(70))}
+${source_default.yellow("__executions__/data-validator.otel.json")}
+
+{
+  "exportedAt": "2025-01-21T10:30:45.123Z",
+  "serviceName": "my-app-tests",
+  "spanCount": 3,
+  "spans": [
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "00f067aa0ba902b7",
+      "parentSpanId": null,
+      "name": "test:data-validator",
+      "kind": "INTERNAL",
+      "startTime": 1703548800000,
+      "endTime": 1703548800150,
+      "duration": 150,
+      "attributes": {
+        "test.name": "data validator success case"
+      },
+      "status": { "code": "OK" },
+      "events": []
+    },
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "abc123def4567890",
+      "parentSpanId": "00f067aa0ba902b7",
+      "name": "validation.started",
+      "kind": "INTERNAL",
+      "startTime": 1703548800010,
+      "endTime": 1703548800015,
+      "duration": 5,
+      "attributes": {
+        "input.recordCount": 100,
+        "input.source": "test-data.csv"
+      },
+      "status": { "code": "OK" },
+      "events": []
+    },
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "def789abc1234567",
+      "parentSpanId": "00f067aa0ba902b7",
+      "name": "validation.complete",
+      "kind": "INTERNAL",
+      "startTime": 1703548800140,
+      "endTime": 1703548800145,
+      "duration": 5,
+      "attributes": {
+        "result.validCount": 95,
+        "result.invalidCount": 5,
+        "duration.ms": 130
+      },
+      "status": { "code": "OK" },
+      "events": []
+    }
+  ]
+}
+
+${source_default.bold("Next Steps:")}
+  ${source_default.cyan("npx @principal-ai/principal-view-cli validate")}          Validate canvas
+  ${source_default.cyan("npx @principal-ai/principal-view-cli narrative validate")} Validate narratives
+  ${source_default.cyan("npx @principal-ai/principal-view-cli validate-execution")}  Validate execution
+`
+};
+function createFormatsCommand() {
+  const command = new Command("formats");
+  command.description("Display documentation about file formats").argument(
+    "[section]",
+    "Section to display: overview, canvas, narrative, execution, examples"
+  ).action((section) => {
+    const validSections = Object.keys(FORMAT_SECTIONS);
+    if (!section) {
+      console.log(FORMAT_SECTIONS.overview);
+      return;
+    }
+    const normalizedSection = section.toLowerCase();
+    if (!validSections.includes(normalizedSection)) {
+      console.log(source_default.red(`Unknown section: ${section}`));
+      console.log(`Valid sections: ${validSections.join(", ")}`);
+      process.exit(1);
+    }
+    console.log(FORMAT_SECTIONS[normalizedSection]);
+  });
+  return command;
+}
+
 // src/commands/doctor.ts
 var import_node_fs8 = require("node:fs");
 var import_node_path9 = require("node:path");
@@ -242919,7 +243409,7 @@ function createNarrativeCommand() {
 }
 
 // src/index.ts
-var VERSION2 = "0.2.1";
+var VERSION2 = "0.2.3";
 var program2 = new Command();
 program2.name("privu").description("Principal View CLI - Validate and manage .canvas configuration files").version(VERSION2);
 program2.addCommand(createInitCommand());
@@ -242929,6 +243419,7 @@ program2.addCommand(createValidateExecutionCommand());
 program2.addCommand(createLintCommand());
 program2.addCommand(createListCommand());
 program2.addCommand(createSchemaCommand());
+program2.addCommand(createFormatsCommand());
 program2.addCommand(createDoctorCommand());
 program2.addCommand(createHooksCommand());
 program2.addCommand(createCoverageCommand());