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

package/dist/index.cjs

@@ -228747,7 +228747,7 @@ function hasOtelFeatures(canvas) {
   }
   return false;
 }
-function validateCanvas(canvas, filePath, library) {
+function validateCanvas(canvas, filePath, library, repositoryPath) {
   const issues = [];
   if (!canvas || typeof canvas !== "object") {
     issues.push({ type: "error", message: "Canvas must be an object" });
@@ -229019,6 +229019,33 @@ function validateCanvas(canvas, filePath, library) {
             issues
           );
         }
+        const hasOtelFeatures2 = nodePv.otel !== void 0 || nodePv.events !== void 0;
+        if (hasOtelFeatures2) {
+          if (!Array.isArray(nodePv.sources) || nodePv.sources.length === 0) {
+            issues.push({
+              type: "error",
+              message: `Node "${nodeLabel}" has OTEL features but is missing required "pv.sources" field`,
+              path: `${nodePath2}.pv.sources`,
+              suggestion: 'Add at least one source file reference, e.g.: "sources": ["src/services/MyService.ts"]'
+            });
+          }
+        }
+        if (Array.isArray(nodePv.sources) && repositoryPath) {
+          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)) {
+                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}`
+                });
+              }
+            }
+          });
+        }
         if (Array.isArray(nodePv.actions)) {
           nodePv.actions.forEach((action, actionIndex) => {
             if (action && typeof action === "object") {
@@ -229230,7 +229257,7 @@ function validateCanvas(canvas, filePath, library) {
   }
   return issues;
 }
-function validateFile(filePath, library) {
+function validateFile(filePath, library, repositoryPath) {
   const absolutePath = (0, import_node_path5.resolve)(filePath);
   const relativePath = (0, import_node_path5.relative)(process.cwd(), absolutePath);
   if (!(0, import_node_fs4.existsSync)(absolutePath)) {
@@ -229243,7 +229270,7 @@ function validateFile(filePath, library) {
   try {
     const content = (0, import_node_fs4.readFileSync)(absolutePath, "utf8");
     const canvas = JSON.parse(content);
-    const issues = validateCanvas(canvas, relativePath, library);
+    const issues = validateCanvas(canvas, relativePath, library, repositoryPath);
     const hasErrors = issues.some((i) => i.type === "error");
     return {
       file: relativePath,
@@ -229264,7 +229291,10 @@ function createValidateCommand() {
   command.description("Validate .canvas configuration files").argument(
     "[files...]",
     "Files or glob patterns to validate (defaults to .principal-views/*.canvas)"
-  ).option("-q, --quiet", "Only output errors").option("--json", "Output results as JSON").action(async (files, options) => {
+  ).option("-q, --quiet", "Only output errors").option("--json", "Output results as JSON").option(
+    "-r, --repository <path>",
+    "Repository root path for validating source file references (defaults to current directory)"
+  ).action(async (files, options) => {
     try {
       const patterns = files.length > 0 ? files : [".principal-views/*.canvas"];
       const matchedFiles = await globby(patterns, {
@@ -229282,6 +229312,7 @@ function createValidateCommand() {
       }
       const principalViewsDir = (0, import_node_path5.resolve)(process.cwd(), ".principal-views");
       const library = loadLibrary(principalViewsDir);
+      const repositoryPath = options.repository ? (0, import_node_path5.resolve)(options.repository) : process.cwd();
       let libraryResult = null;
       if (library && Object.keys(library.raw).length > 0) {
         const libraryIssues = validateLibrary(library);
@@ -229292,7 +229323,9 @@ function createValidateCommand() {
           issues: libraryIssues
         };
       }
-      const results = matchedFiles.map((f) => validateFile(f, library));
+      const results = matchedFiles.map(
+        (f) => validateFile(f, library, repositoryPath)
+      );
       const allResults = libraryResult ? [libraryResult, ...results] : results;
       const validCount = allResults.filter((r) => r.isValid).length;
       const invalidCount = allResults.length - validCount;
@@ -241078,6 +241111,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");
@@ -242886,7 +243391,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());
@@ -242896,6 +243401,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());