@vpxa/aikit 0.1.179 → 0.1.181

package/scaffold/dist/definitions/skills/docs.mjs

@@ -837,7 +837,10 @@ docs/
   ├── index.md             # Tour listing with descriptions
   ├── architecture.md      # System structure tour
   ├── data-flow.md         # Data pipeline tour
-  └── feature-{name}.md    # Feature-specific tours
+  ├── feature-{name}.md    # Feature-specific tours
+  └── interactive/
+    ├── {name}.json        # Tour data injected into viewer
+    └── {name}.html        # Interactive viewer output
 \`\`\`
 
 ## Interactive JSON Tour (Recommended)
@@ -851,16 +854,16 @@ Tour data must conform to [references/tour.schema.json](references/tour.schema.j
 ### Usage (MANDATORY — every tour MUST produce interactive HTML)
 
 Every tour MUST produce both:
-- \`docs/tours/{name}.tour.json\` — machine-readable data
+- \`docs/tours/interactive/{name}.json\` — machine-readable data
 - \`docs/tours/interactive/{name}.html\` — interactive viewer for humans
 
 Steps:
 1. Generate JSON that conforms to [references/tour.schema.json](references/tour.schema.json)
-2. Save JSON to \`docs/tours/{name}.tour.json\`
+2. Save JSON to \`docs/tours/interactive/{name}.json\`
 3. Create interactive HTML by running the injection script:
 
 \`\`\`bash
-node scripts/inject-viewer.mjs --template assets/tour-viewer.html --data docs/tours/{name}.tour.json --out docs/tours/interactive/{name}.html
+node scripts/inject-viewer.mjs --template assets/tour-viewer.html --data docs/tours/interactive/{name}.json --out docs/tours/interactive/{name}.html
 \`\`\`
 
 The script reads the viewer template, injects tour JSON data, and writes the output HTML. Cross-platform, no dependencies.
@@ -871,6 +874,7 @@ The script reads the viewer template, injects tour JSON data, and writes the out
 {
   "title": "Authentication Tour",
   "description": "Walk through the login path from entry point to token issuance.",
+  "estimatedTime": "12 min",
   "version": "1.0.0",
   "metadata": {
     "author": "AI Kit",
@@ -880,33 +884,27 @@ The script reads the viewer template, injects tour JSON data, and writes the out
   },
   "steps": [
     {
+      "stepNumber": 1,
       "id": "entry-point",
       "title": "Request Entry",
-      "description": "This handler receives the login request, validates the outer shape, and forwards work to the auth service.",
+      "explanation": "This handler receives the login request, validates the outer shape, and forwards work to the auth service. It exists to keep malformed input from reaching credential and token logic deeper in the stack. The route uses boundary validation first, then hands the normalized request to the auth service so downstream code can assume a known shape. This step connects the public HTTP surface to the internal authentication pipeline.",
       "file": "src/http/routes/login.ts",
       "line": 1,
       "endLine": 28,
+      "learnsConcept": "Request boundary validation",
+      "duration": "2 min",
       "language": "ts",
       "codeSnippet": "export async function loginRoute(req, res) { /* ... */ }",
-      "highlights": [
-        {
-          "line": 8,
-          "label": "Request validation starts here",
-          "style": "info"
-        }
-      ],
-      "notes": [
-        "Introduces the request boundary.",
-        "The main concept here is input validation before auth logic."
-      ]
+      "notes": "Introduces the request boundary and shows why validation happens before auth logic."
     }
-  ]
+  ],
+  "dependencies": []
 }
 \`\`\`
 
 ### Step Content Quality Requirements
 
-Each tour step description MUST include ALL of these elements:
+Each tour step explanation MUST include ALL of these elements:
 
 1. **What** — What this code does (1 sentence)
 2. **Why** — Why it exists, what problem it solves, what would break without it (1-2 sentences)
@@ -916,30 +914,32 @@ Each tour step description MUST include ALL of these elements:
 **Bad example (too shallow):**
 \`\`\`json
 {
+  "stepNumber": 3,
+  "id": "preview-generator",
   "title": "The preview generator",
-  "description": "This file registers the skills adapter for generating preview files.",
-  "notes": ["Entry point for the build pipeline."]
+  "explanation": "This file registers the skills adapter for generating preview files."
 }
 \`\`\`
 
 **Good example (deep, educational):**
 \`\`\`json
 {
+  "stepNumber": 3,
+  "id": "skills-adapter-registration",
   "title": "Skills Adapter Registration",
-  "description": "generate.mjs registers the skills adapter — a function that reads .mjs skill definitions and transforms them into deployable SKILL.md + reference files. Without this adapter, the build pipeline has no way to discover or process skill sources. It uses a plugin pattern where each adapter (skills, prompts, agents) is registered independently, allowing the pipeline to process different artifact types through a unified interface.",
-  "notes": ["This is the entry point that connects raw .mjs definitions to the full build output. The adapter pattern means adding a new artifact type (e.g., workflows) requires only registering a new adapter — no changes to the core pipeline. Watch for the 'definitions' directory scan that feeds into this adapter."],
-  "highlights": [
-    { "line": 30, "endLine": 45, "label": "Adapter registration block — each registerAdapter() call wires a definition type to its generator" }
-  ]
+  "explanation": "generate.mjs registers the skills adapter — a function that reads .mjs skill definitions and transforms them into deployable SKILL.md + reference files. Without this adapter, the build pipeline has no way to discover or process skill sources. It uses a plugin pattern where each adapter (skills, prompts, agents) is registered independently, allowing the pipeline to process different artifact types through a unified interface. This step matters because it is the bridge between raw authoring inputs and every generated documentation artifact downstream.",
+  "learnsConcept": "Adapter-based generation pipelines",
+  "duration": "3 min",
+  "notes": "This is the entry point that connects raw .mjs definitions to the full build output. Watch for the definitions directory scan that feeds into the adapter."
 }
 \`\`\`
 
 **Quality bar:** If a developer reads only the tour (without opening any files), they should understand the system's architecture, design decisions, and data flow.
 
 **Minimum requirements per step:**
-- Description: 3-5 sentences minimum (not 1-2)
-- Notes: 2-3 sentences explaining architectural significance
-- Highlights: At least 1 per step with meaningful labels (not just line numbers)
+- Explanation: 3-5 sentences minimum (not 1-2)
+- Notes: Optional, but when present use 1-2 sentences explaining architectural significance
+- Include \`stepNumber\`, \`id\`, \`duration\`, and \`learnsConcept\` for every step
 - codeSnippet: Include for steps where the key logic fits in <15 lines
 
 ### Line Number Validation (MANDATORY)
@@ -956,7 +956,7 @@ After generating tour JSON, validate EVERY step's line numbers against the actua
 For each step:
   compact({ path: step.file, query: step.title })  → find actual location
   read_file(step.file, step.line, step.line + 10)   → verify code matches description
-  If mismatch → search({ query: step.description }) → find correct file:line
+  If mismatch → search({ query: step.explanation }) → find correct file:line
 \`\`\`
 
 Tour JSON with stale line numbers is a **quality gate failure**. Fix before saving.
@@ -965,15 +965,17 @@ Tour JSON with stale line numbers is a **quality gate failure**. Fix before savi
 
 1. **title**: Use a reader-facing tour name.
 2. **description**: State the tour goal and scope in one or two sentences.
-3. **version**: Set the schema version you are targeting.
-4. **metadata**: Use optional metadata for authoring info, tags, timestamps, and difficulty.
-5. **steps**: Order is defined by array position. Do not add a separate ordinal field.
-6. **id**: Optional but recommended for stable references and analytics; use descriptive kebab-case when present.
-7. **description** on each step: Explain what matters in this step and why it belongs in the tour.
-8. **file**, **line**, and **endLine**: Point to the exact source span when possible.
-9. **codeSnippet** and **language**: Provide a fallback snippet when the viewer cannot load the file directly.
-10. **highlights**: Use line annotations for the few lines the reader should notice first.
-11. **notes**: Capture concepts, tips, cautions, or prerequisite reminders that do not belong in the main description.
+3. **estimatedTime**: Include a reader-facing duration for the full tour, such as \`15 min\`.
+4. **version**: Set the schema version you are targeting.
+5. **metadata**: Use optional metadata for authoring info, tags, timestamps, and difficulty.
+6. **steps**: Keep array order aligned with the explicit \`stepNumber\` field.
+7. **id**: Required for stable references and dependency edges; use descriptive kebab-case.
+8. **explanation** on each step: Explain what matters in this step and why it belongs in the tour.
+9. **file**, **line**, and **endLine**: Point to the exact source span when possible.
+10. **learnsConcept** and **duration**: Use them to make the learning goal and reading effort explicit.
+11. **codeSnippet** and **language**: Provide a fallback snippet when the viewer cannot load the file directly.
+12. **notes**: Capture concepts, tips, cautions, or prerequisite reminders that do not belong in the main explanation.
+13. **dependencies**: Use step ids to describe prerequisite or flow relationships when the graph should show them.
 
 Mapping from the old contract to the current schema:
 
@@ -1185,7 +1187,7 @@ docs/
   "description": "Schema for AI Kit interactive code tour data. The agent generates JSON matching this schema, which is injected into tour-viewer.html.",
   "version": "1.0.0",
   "type": "object",
-  "required": ["title", "steps"],
+  "required": ["title", "description", "estimatedTime", "steps"],
   "properties": {
     "title": {
       "type": "string",
@@ -1195,6 +1197,10 @@ docs/
       "type": "string",
       "description": "Brief tour description shown below the title"
     },
+    "estimatedTime": {
+      "type": "string",
+      "description": "Estimated reading time (e.g., '15 min')"
+    },
     "version": {
       "type": "string",
       "description": "Schema version for forward compatibility",
@@ -1214,15 +1220,25 @@ docs/
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["title", "description"],
+        "required": ["title", "explanation", "id", "stepNumber"],
         "properties": {
+          "stepNumber": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based step order number"
+          },
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$",
+            "description": "Kebab-case unique step identifier (used in dependency graph)"
+          },
           "title": {
             "type": "string",
             "description": "Step title shown in navigation"
           },
-          "description": {
+          "explanation": {
             "type": "string",
-            "description": "Markdown content explaining this step"
+            "description": "Detailed explanation of what this code does and why it matters (3-5 sentences minimum)"
           },
           "file": {
             "type": "string",
@@ -1236,6 +1252,14 @@ docs/
             "type": "integer",
             "description": "Ending line number (for range highlights)"
           },
+          "learnsConcept": {
+            "type": "string",
+            "description": "Key concept this step teaches (displayed as concept tag)"
+          },
+          "duration": {
+            "type": "string",
+            "description": "Estimated reading time for this step (e.g., '2 min')"
+          },
           "codeSnippet": {
             "type": "string",
             "description": "Code snippet to display if file is not available"
@@ -1244,26 +1268,24 @@ docs/
             "type": "string",
             "description": "Language for syntax highlighting of codeSnippet"
           },
-          "highlights": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "properties": {
-                "line": { "type": "integer" },
-                "label": { "type": "string" },
-                "style": { "type": "string", "enum": ["info", "warning", "error", "success"] }
-              },
-              "required": ["line"]
-            },
-            "description": "Line-level highlights within the code"
-          },
           "notes": {
-            "type": "array",
-            "items": { "type": "string" },
-            "description": "Additional callouts or tips for this step"
+            "type": "string",
+            "description": "Additional notes for this step"
           }
         }
       }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target"],
+        "properties": {
+          "source": { "type": "string", "description": "Source step id" },
+          "target": { "type": "string", "description": "Target step id" }
+        }
+      },
+      "description": "Step dependency edges for the graph visualization"
     }
   }
 }`},{file:`references/generation-pipeline.md`,content:`# Generation Pipeline Reference
@@ -2595,11 +2617,11 @@ PRDs go in \`docs/prd/PRD-NNN-descriptive-name.md\`. The index lives at \`docs/p
 Detailed instructions in [references/tour-generation.md](references/tour-generation.md).
 
 **MANDATORY outputs** for every tour:
-1. \`docs/tours/{name}.tour.json\` — data (must conform to [tour.schema.json](references/tour.schema.json))
+1. \`docs/tours/interactive/{name}.json\` — data (must conform to [tour.schema.json](references/tour.schema.json))
 2. \`docs/tours/interactive/{name}.html\` — interactive viewer (inject JSON into shipped \`assets/tour-viewer.html\`)
 
 **Content quality bar:**
-- Each step: 3-5 sentence description (what/why/how/connection), 2-3 sentence notes, ≥1 highlight
+- Each step: 3-5 sentence explanation (what/why/how/connection), include \`stepNumber\`, \`id\`, \`duration\`, and \`learnsConcept\`
 - Line numbers MUST be validated against actual source files before saving
 - A developer reading only the tour should understand the system without opening files