@forwardimpact/pathway 0.3.0 → 0.4.0

package/app/formatters/agent/skill.js

@@ -10,6 +10,47 @@
 
 import Mustache from "mustache";
 
+import { trimValue, splitLines, trimFields } from "../shared.js";
+
+/**
+ * Prepare agent skill data for template rendering
+ * Normalizes string values by trimming trailing newlines for consistent template output.
+ * @param {Object} params
+ * @param {Object} params.frontmatter - YAML frontmatter data
+ * @param {string} params.frontmatter.name - Skill name (required)
+ * @param {string} params.frontmatter.description - Skill description (required)
+ * @param {string} [params.frontmatter.useWhen] - When to use this skill
+ * @param {string} params.title - Human-readable skill title for heading
+ * @param {Array} params.stages - Array of stage objects with stageName, focus, activities, ready
+ * @param {string} params.reference - Reference content (markdown)
+ * @param {Array} [params.toolReferences] - Array of tool reference objects
+ * @returns {Object} Data object ready for Mustache template
+ */
+function prepareAgentSkillData({
+  frontmatter,
+  title,
+  stages,
+  reference,
+  toolReferences,
+}) {
+  // Process stages - trim focus and array values
+  const processedStages = trimFields(stages, {
+    focus: "required",
+    activities: "array",
+    ready: "array",
+  });
+
+  return {
+    name: frontmatter.name,
+    descriptionLines: splitLines(frontmatter.description),
+    useWhenLines: splitLines(frontmatter.useWhen),
+    title,
+    stages: processedStages,
+    reference: trimValue(reference) || "",
+    toolReferences: toolReferences || [],
+  };
+}
+
 /**
  * Format agent skill as SKILL.md file content using Mustache template
  * @param {Object} skill - Skill with frontmatter, title, stages, reference
@@ -19,19 +60,20 @@ import Mustache from "mustache";
  * @param {string} skill.title - Human-readable skill title for heading
  * @param {Array} skill.stages - Array of stage objects with stageName, focus, activities, ready
  * @param {string} skill.reference - Reference content (markdown)
+ * @param {Array} [skill.toolReferences] - Array of tool reference objects
  * @param {string} template - Mustache template string
  * @returns {string} Complete SKILL.md file content
  */
 export function formatAgentSkill(
-  { frontmatter, title, stages, reference },
+  { frontmatter, title, stages, reference, toolReferences },
   template,
 ) {
-  const data = {
-    name: frontmatter.name,
-    descriptionLines: frontmatter.description.trim().split("\n"),
+  const data = prepareAgentSkillData({
+    frontmatter,
     title,
     stages,
-    reference: reference ? reference.trim() : "",
-  };
+    reference,
+    toolReferences,
+  });
   return Mustache.render(template, data);
 }

package/app/formatters/job/description.js

@@ -14,6 +14,7 @@ import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
 } from "../../model/levels.js";
+import { trimValue, trimFields } from "../shared.js";
 
 /**
  * Prepare job data for template rendering
@@ -121,28 +122,32 @@ function prepareJobDescriptionData({ job, discipline, grade, track }) {
     };
   });
 
+  // Build qualification summary with placeholder replacement
+  const qualificationSummary =
+    (grade.qualificationSummary || "").replace(
+      /\{typicalExperienceRange\}/g,
+      grade.typicalExperienceRange || "",
+    ) || null;
+
   return {
     title: job.title,
     gradeId: grade.id,
     typicalExperienceRange: grade.typicalExperienceRange,
     trackName: track?.name || null,
-    roleSummary,
-    trackRoleContext: track?.roleContext || null,
-    expectationsParagraph: expectationsParagraph || null,
-    responsibilities: (job.derivedResponsibilities || []).map((r) => ({
-      capabilityName: r.capabilityName,
-      responsibility: r.responsibility,
-    })),
-    behaviours: sortedBehaviours.map((b) => ({
-      behaviourName: b.behaviourName,
-      maturityDescription: b.maturityDescription || "",
+    roleSummary: trimValue(roleSummary),
+    trackRoleContext: trimValue(track?.roleContext),
+    expectationsParagraph: trimValue(expectationsParagraph),
+    responsibilities: trimFields(job.derivedResponsibilities, {
+      responsibility: "required",
+    }),
+    behaviours: trimFields(sortedBehaviours, {
+      maturityDescription: "optional",
+    }),
+    skillLevels: skillLevels.map((level) => ({
+      ...level,
+      skills: trimFields(level.skills, { levelDescription: "optional" }),
     })),
-    skillLevels,
-    qualificationSummary:
-      (grade.qualificationSummary || "").replace(
-        /\{typicalExperienceRange\}/g,
-        grade.typicalExperienceRange || "",
-      ) || null,
+    qualificationSummary: trimValue(qualificationSummary),
   };
 }
 

package/app/formatters/job/dom.js

@@ -2,7 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import { div, h1, h2, p, a, span, button, section } from "../../lib/render.js";
+import { div, h1, h2, p, a, span, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -14,6 +14,7 @@ import {
 } from "../../components/radar-chart.js";
 import { createSkillMatrix } from "../../components/skill-matrix.js";
 import { createBehaviourProfile } from "../../components/behaviour-profile.js";
+import { createMarkdownTextarea } from "../../components/markdown-textarea.js";
 import { markdownToHtml } from "../../lib/markdown.js";
 import { formatJobDescription } from "./description.js";
 
@@ -223,77 +224,15 @@ export function createJobDescriptionSection({
     template,
   );
 
-  const copyButton = button(
-    {
-      className: "btn btn-primary copy-btn",
-      onClick: async () => {
-        try {
-          await navigator.clipboard.writeText(markdown);
-          copyButton.textContent = "✓ Copied!";
-          copyButton.classList.add("copied");
-          setTimeout(() => {
-            copyButton.textContent = "Copy Markdown";
-            copyButton.classList.remove("copied");
-          }, 2000);
-        } catch (err) {
-          console.error("Failed to copy:", err);
-          copyButton.textContent = "Copy failed";
-          setTimeout(() => {
-            copyButton.textContent = "Copy Markdown";
-          }, 2000);
-        }
-      },
-    },
-    "Copy Markdown",
-  );
-
-  const copyHtmlButton = button(
-    {
-      className: "btn btn-secondary copy-btn",
-      onClick: async () => {
-        try {
-          const html = markdownToHtml(markdown);
-          // Use ClipboardItem with text/html MIME type for rich text pasting in Word
-          const blob = new Blob([html], { type: "text/html" });
-          const clipboardItem = new ClipboardItem({ "text/html": blob });
-          await navigator.clipboard.write([clipboardItem]);
-          copyHtmlButton.textContent = "✓ Copied!";
-          copyHtmlButton.classList.add("copied");
-          setTimeout(() => {
-            copyHtmlButton.textContent = "Copy as HTML";
-            copyHtmlButton.classList.remove("copied");
-          }, 2000);
-        } catch (err) {
-          console.error("Failed to copy:", err);
-          copyHtmlButton.textContent = "Copy failed";
-          setTimeout(() => {
-            copyHtmlButton.textContent = "Copy as HTML";
-          }, 2000);
-        }
-      },
-    },
-    "Copy as HTML",
-  );
-
-  const textarea = document.createElement("textarea");
-  textarea.className = "job-description-textarea";
-  textarea.readOnly = true;
-  textarea.value = markdown;
-
   return createDetailSection({
     title: "Job Description",
-    content: div(
-      { className: "job-description-container" },
-      div(
-        { className: "job-description-header" },
-        p(
-          { className: "text-muted" },
-          "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
-        ),
-        div({ className: "button-group" }, copyButton, copyHtmlButton),
-      ),
-      textarea,
-    ),
+    content: createMarkdownTextarea({
+      markdown,
+      description:
+        "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
+      toHtml: markdownToHtml,
+      minHeight: 450,
+    }),
   });
 }
 

package/app/formatters/shared.js

@@ -4,6 +4,64 @@
  * Common formatting functions used across different output formats (CLI, DOM, markdown)
  */
 
+/**
+ * Trim trailing newlines from a string value
+ * Used by template prepare functions for consistent output formatting.
+ * @param {string|null|undefined} value - Value to trim
+ * @returns {string|null} Trimmed value or null if empty
+ */
+export function trimValue(value) {
+  if (value == null) return null;
+  const trimmed = value.replace(/\n+$/, "");
+  return trimmed || null;
+}
+
+/**
+ * Trim a required field, preserving original if trim would result in empty
+ * Use for fields that must have a value.
+ * @param {string|null|undefined} value - Value to trim
+ * @returns {string} Trimmed value or original
+ */
+export function trimRequired(value) {
+  return trimValue(value) || value || "";
+}
+
+/**
+ * Trim and split a string into lines
+ * @param {string|null|undefined} value - Value to process
+ * @returns {string[]} Array of lines (empty array if no value)
+ */
+export function splitLines(value) {
+  const trimmed = trimValue(value);
+  return trimmed ? trimmed.split("\n") : [];
+}
+
+/**
+ * Transform an array of objects by applying trimValue to specified fields
+ * @param {Array<Object>} array - Array of objects to transform
+ * @param {Object<string, 'optional'|'required'|'array'>} fieldSpec - Fields to trim and their type
+ *   - 'optional': use trimValue (returns null if empty)
+ *   - 'required': use trimRequired (preserves original if empty)
+ *   - 'array': trim each element in array field
+ * @returns {Array<Object>} Transformed array
+ */
+export function trimFields(array, fieldSpec) {
+  if (!array) return [];
+  return array.map((item) => {
+    const result = { ...item };
+    for (const [field, type] of Object.entries(fieldSpec)) {
+      if (type === "optional") {
+        result[field] = trimValue(item[field]);
+      } else if (type === "required") {
+        result[field] = trimRequired(item[field]);
+      } else if (type === "array") {
+        result[field] = (item[field] || []).map((v) => trimRequired(v));
+      }
+    }
+    return result;
+  });
+}
+
 /**
  * Format level as text with dots (for CLI/markdown)
  * @param {number} level - 1-5

package/app/formatters/skill/dom.js

@@ -18,8 +18,9 @@ import {
 } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
+import { createMarkdownTextarea } from "../../components/markdown-textarea.js";
 import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
-import { prepareSkillDetail, formatCapability } from "./shared.js";
+import { prepareSkillDetail } from "./shared.js";
 import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
 
 /**
@@ -61,7 +62,7 @@ export function skillToDOM(
         { className: "page-meta" },
         span(
           { className: "badge badge-default" },
-          formatCapability(view.capability),
+          `${view.capabilityEmoji} ${view.capability.toUpperCase()}`,
         ),
         view.isHumanOnly
           ? span(
@@ -97,6 +98,60 @@ export function skillToDOM(
       ),
     ),
 
+    // Recommended Tools
+    view.toolReferences.length > 0
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Recommended Tools"),
+          table(
+            { className: "tools-table" },
+            thead({}, tr({}, th({}, "Tool"), th({}, "Use When"))),
+            tbody(
+              {},
+              ...view.toolReferences.map((tool) =>
+                tr(
+                  {},
+                  td(
+                    {},
+                    tool.url
+                      ? a(
+                          {
+                            href: tool.url,
+                            target: "_blank",
+                            rel: "noopener noreferrer",
+                          },
+                          tool.name,
+                        )
+                      : tool.name,
+                  ),
+                  td({}, tool.useWhen),
+                ),
+              ),
+            ),
+          ),
+          showBackLink
+            ? p(
+                { className: "see-all-link" },
+                a({ href: "#/tool" }, "See all tools →"),
+              )
+            : null,
+        )
+      : null,
+
+    // Implementation Reference
+    view.implementationReference
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Implementation Patterns"),
+          createMarkdownTextarea({
+            markdown: view.implementationReference,
+            description:
+              "Project-specific implementation guidance for this skill.",
+            minHeight: 450,
+          }),
+        )
+      : null,
+
     // Used in Disciplines and Linked to Drivers in two columns
     view.relatedDisciplines.length > 0 || view.relatedDrivers.length > 0
       ? div(

package/app/formatters/skill/markdown.js

@@ -105,5 +105,23 @@ export function skillToMarkdown(
     lines.push("");
   }
 
+  // Recommended tools
+  if (view.toolReferences.length > 0) {
+    lines.push("## Recommended Tools", "");
+    const toolRows = view.toolReferences.map((tool) => [
+      tool.url ? `[${tool.name}](${tool.url})` : tool.name,
+      tool.useWhen,
+    ]);
+    lines.push(tableToMarkdown(["Tool", "Use When"], toolRows));
+    lines.push("");
+  }
+
+  // Implementation reference
+  if (view.implementationReference) {
+    lines.push("## Implementation Patterns", "");
+    lines.push(view.implementationReference);
+    lines.push("");
+  }
+
   return lines.join("\n");
 }

package/app/formatters/skill/shared.js

@@ -13,12 +13,12 @@ import { truncate } from "../shared.js";
 
 /**
  * Format capability name for display
- * @param {string} capability
+ * @param {string} capabilityName - The capability name to display
  * @returns {string}
  */
-export function formatCapability(capability) {
-  if (!capability) return "";
-  return capability.charAt(0).toUpperCase() + capability.slice(1);
+export function formatCapability(capabilityName) {
+  if (!capabilityName) return "";
+  return capabilityName;
 }
 
 /**
@@ -66,12 +66,15 @@ export function prepareSkillsList(
  * @property {string} name
  * @property {string} description
  * @property {string} capability
+ * @property {string} capabilityName
  * @property {boolean} isHumanOnly
  * @property {string} capabilityEmoji
  * @property {Object<string, string>} levelDescriptions
  * @property {Array<{id: string, name: string, skillType: string}>} relatedDisciplines
  * @property {Array<{id: string, name: string, modifier: number}>} relatedTracks
  * @property {Array<{id: string, name: string}>} relatedDrivers
+ * @property {Array<{name: string, url?: string, description: string, useWhen: string}>} toolReferences
+ * @property {string|null} implementationReference
  */
 
 /**
@@ -110,16 +113,21 @@ export function prepareSkillDetail(
     .filter((d) => d.contributingSkills?.includes(skill.id))
     .map((d) => ({ id: d.id, name: d.name }));
 
+  const capabilityEntity = capabilities.find((c) => c.id === skill.capability);
+
   return {
     id: skill.id,
     name: skill.name,
     description: skill.description,
     capability: skill.capability,
+    capabilityName: capabilityEntity?.name || skill.capability,
     isHumanOnly: skill.isHumanOnly || false,
     capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
     levelDescriptions: skill.levelDescriptions,
     relatedDisciplines,
     relatedTracks,
     relatedDrivers,
+    toolReferences: skill.toolReferences || [],
+    implementationReference: skill.implementationReference || null,
   };
 }

package/app/formatters/stage/microdata.js

@@ -32,7 +32,7 @@ export function stageListToMicrodata(stages) {
           ? `→ ${stage.handoffs.map((h) => h.target).join(", ")}`
           : "";
       return `${openTag("article", { itemtype: "Stage", itemid: `#${stage.id}` })}
-${prop("h2", "name", `${stage.emoji || ""} ${stage.name}`)}
+${prop("h2", "name", `${stage.emoji} ${stage.name}`)}
 ${prop("p", "description", stage.truncatedDescription)}
 ${handoffText ? `<p>Handoffs: ${handoffText}</p>` : ""}
 </article>`;

package/app/formatters/stage/shared.js

@@ -80,5 +80,5 @@ export function prepareStageDetail(stage) {
  */
 export function getStageEmoji(stages, stageId) {
   const stage = stages.find((s) => s.id === stageId);
-  return stage?.emoji || "🔄";
+  return stage?.emoji;
 }

package/app/formatters/tool/shared.js

@@ -0,0 +1,72 @@
+/**
+ * Tool presentation helpers
+ *
+ * Shared utilities for formatting tool data across DOM and CLI outputs.
+ */
+
+/**
+ * @typedef {Object} ToolUsage
+ * @property {string} skillId
+ * @property {string} skillName
+ * @property {string} capabilityId
+ * @property {string} useWhen
+ */
+
+/**
+ * @typedef {Object} AggregatedTool
+ * @property {string} name
+ * @property {string} [url]
+ * @property {string} description
+ * @property {ToolUsage[]} usages
+ */
+
+/**
+ * Aggregate tools from all skills, deduplicating by name
+ * @param {Array} skills - All skills with toolReferences
+ * @returns {AggregatedTool[]}
+ */
+export function aggregateTools(skills) {
+  const toolMap = new Map();
+
+  for (const skill of skills) {
+    if (!skill.toolReferences) continue;
+
+    for (const tool of skill.toolReferences) {
+      const usage = {
+        skillId: skill.id,
+        skillName: skill.name,
+        capabilityId: skill.capability,
+        useWhen: tool.useWhen,
+      };
+
+      const existing = toolMap.get(tool.name);
+      if (existing) {
+        existing.usages.push(usage);
+      } else {
+        toolMap.set(tool.name, {
+          name: tool.name,
+          url: tool.url,
+          description: tool.description,
+          usages: [usage],
+        });
+      }
+    }
+  }
+
+  return Array.from(toolMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
+
+/**
+ * Prepare tools list view data
+ * @param {Array} skills - All skills
+ * @returns {{ tools: AggregatedTool[], totalCount: number }}
+ */
+export function prepareToolsList(skills) {
+  const tools = aggregateTools(skills);
+  return {
+    tools,
+    totalCount: tools.length,
+  };
+}

package/app/handout-main.js

@@ -135,25 +135,25 @@ function renderIndex(data) {
             `${getConceptEmoji(framework, "job")} ${framework.entityDefinitions.job.title}`,
           ),
           " - ",
-          `${data.disciplines.length} disciplines, ${data.tracks.length} tracks, ${data.grades.length} grades`,
+          `${data.disciplines.length} disciplines, ${data.grades.length} grades, ${data.tracks.length} tracks`,
         ),
         li(
           {},
           a(
-            { href: "#/skill" },
-            `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
+            { href: "#/behaviour" },
+            `${getConceptEmoji(framework, "behaviour")} ${framework.entityDefinitions.behaviour.title}`,
           ),
           " - ",
-          `${data.skills.length} skill definitions`,
+          `${data.behaviours.length} behaviour definitions`,
         ),
         li(
           {},
           a(
-            { href: "#/behaviour" },
-            `${getConceptEmoji(framework, "behaviour")} ${framework.entityDefinitions.behaviour.title}`,
+            { href: "#/skill" },
+            `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
           ),
           " - ",
-          `${data.behaviours.length} behaviour definitions`,
+          `${data.skills.length} skill definitions`,
         ),
         li(
           {},

package/app/index.html

@@ -5,6 +5,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Engineering Pathway</title>
     <link rel="stylesheet" href="css/bundles/app.css" />
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-markdown.min.js"></script>
     <script type="importmap">
       {
         "imports": {
@@ -31,12 +37,13 @@
         </button>
         <ul class="nav-links" id="nav-links">
           <li><a href="#/discipline">Disciplines</a></li>
-          <li><a href="#/track">Tracks</a></li>
           <li><a href="#/grade">Grades</a></li>
-          <li><a href="#/skill">Skills</a></li>
+          <li><a href="#/track">Tracks</a></li>
           <li><a href="#/behaviour">Behaviours</a></li>
-          <li><a href="#/stage">Stages</a></li>
+          <li><a href="#/skill">Skills</a></li>
           <li><a href="#/driver">Drivers</a></li>
+          <li><a href="#/stage">Stages</a></li>
+          <li><a href="#/tool">Tools</a></li>
           <li><a href="#/job-builder" class="nav-cta">Build a Job</a></li>
           <li><a href="#/agent-builder" class="nav-cta">Build an Agent</a></li>
           <li><a href="#/interview-prep" class="nav-cta">Interview Prep</a></li>