@forwardimpact/pathway 0.4.0 → 0.5.0

package/app/formatters/skill/dom.js

@@ -18,7 +18,8 @@ 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 { createCodeDisplay } from "../../components/code-display.js";
+import { createToolIcon } from "../../lib/card-mappers.js";
 import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
 import { prepareSkillDetail } from "./shared.js";
 import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
@@ -32,11 +33,19 @@ import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
  * @param {Array} context.drivers - All drivers
  * @param {Array} context.capabilities - Capability entities
  * @param {boolean} [context.showBackLink=true] - Whether to show back navigation link
+ * @param {boolean} [context.showToolsAndPatterns=true] - Whether to show recommended tools and implementation patterns
  * @returns {HTMLElement}
  */
 export function skillToDOM(
   skill,
-  { disciplines, tracks, drivers, capabilities, showBackLink = true } = {},
+  {
+    disciplines,
+    tracks,
+    drivers,
+    capabilities,
+    showBackLink = true,
+    showToolsAndPatterns = true,
+  } = {},
 ) {
   const view = prepareSkillDetail(skill, {
     disciplines,
@@ -98,60 +107,6 @@ 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(
@@ -222,5 +177,62 @@ export function skillToDOM(
           ),
         )
       : null,
+
+    // Recommended Tools
+    showToolsAndPatterns && 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(
+                    { className: "tool-name-cell" },
+                    tool.simpleIcon
+                      ? createToolIcon(tool.simpleIcon, tool.name)
+                      : null,
+                    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
+    showToolsAndPatterns && view.implementationReference
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Implementation Patterns"),
+          createCodeDisplay({
+            content: view.implementationReference,
+            description:
+              "Project-specific implementation guidance for this skill.",
+            minHeight: 450,
+          }),
+        )
+      : null,
   );
 }

package/app/formatters/skill/shared.js

@@ -127,7 +127,9 @@ export function prepareSkillDetail(
     relatedDisciplines,
     relatedTracks,
     relatedDrivers,
-    toolReferences: skill.toolReferences || [],
+    toolReferences: (skill.toolReferences || [])
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name)),
     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.emojiIcon} ${stage.name}`)}
 ${prop("p", "description", stage.truncatedDescription)}
 ${handoffText ? `<p>Handoffs: ${handoffText}</p>` : ""}
 </article>`;
@@ -100,7 +100,7 @@ ${prop("p", "prompt", h.prompt)}
 ${openTag("article", { itemtype: "Stage", itemid: `#${view.id}` })}
 ${prop("h1", "name", view.name)}
 ${metaTag("id", view.id)}
-${stage.emoji ? metaTag("emoji", stage.emoji) : ""}
+${stage.emojiIcon ? metaTag("emojiIcon", stage.emojiIcon) : ""}
 ${prop("p", "description", view.description)}
 ${sections.join("\n")}
 </article>

package/app/formatters/stage/shared.js

@@ -10,7 +10,7 @@ import { truncate } from "../shared.js";
  * @typedef {Object} StageListItem
  * @property {string} id
  * @property {string} name
- * @property {string} emoji
+ * @property {string} emojiIcon
  * @property {string} description
  * @property {string} truncatedDescription
  * @property {Array<{target: string, label: string}>} handoffs
@@ -27,7 +27,7 @@ export function prepareStagesList(stages, descriptionLimit = 150) {
     return {
       id: stage.id,
       name: stage.name,
-      emoji: stage.emoji,
+      emojiIcon: stage.emojiIcon,
       description: stage.description,
       truncatedDescription: truncate(stage.description, descriptionLimit),
       handoffs: (stage.handoffs || []).map((h) => ({
@@ -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?.emojiIcon;
 }

package/app/formatters/tool/shared.js

@@ -16,6 +16,7 @@
  * @typedef {Object} AggregatedTool
  * @property {string} name
  * @property {string} [url]
+ * @property {string} [simpleIcon]
  * @property {string} description
  * @property {ToolUsage[]} usages
  */
@@ -42,10 +43,15 @@ export function aggregateTools(skills) {
       const existing = toolMap.get(tool.name);
       if (existing) {
         existing.usages.push(usage);
+        // Prefer simpleIcon from first occurrence that has one
+        if (!existing.simpleIcon && tool.simpleIcon) {
+          existing.simpleIcon = tool.simpleIcon;
+        }
       } else {
         toolMap.set(tool.name, {
           name: tool.name,
           url: tool.url,
+          simpleIcon: tool.simpleIcon,
           description: tool.description,
           usages: [usage],
         });

package/app/handout-main.js

@@ -41,17 +41,17 @@ import { sortTracksByName } from "./formatters/track/shared.js";
 /**
  * Create a chapter cover page
  * @param {Object} params
- * @param {string} params.emoji - Chapter emoji
+ * @param {string} params.emojiIcon - Chapter emoji
  * @param {string} params.title - Chapter title
  * @param {string} params.description - Chapter description
  * @returns {HTMLElement}
  */
-function createChapterCover({ emoji, title, description }) {
+function createChapterCover({ emojiIcon, title, description }) {
   return div(
     { className: "chapter-cover" },
     h1(
       { className: "chapter-title" },
-      emoji,
+      emojiIcon,
       " ",
       span({ className: "gradient-text" }, title),
     ),
@@ -111,7 +111,7 @@ function renderIndex(data) {
       { className: "page-header" },
       heading1(
         { className: "page-title" },
-        `${framework.emoji} ${framework.title} Handouts`,
+        `${framework.emojiIcon} ${framework.title} Handouts`,
       ),
       p(
         { className: "page-description" },
@@ -190,7 +190,7 @@ function renderDriverHandout(data) {
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "driver"),
+      emojiIcon: getConceptEmoji(framework, "driver"),
       title: framework.entityDefinitions.driver.title,
       description: framework.entityDefinitions.driver.description,
     }),
@@ -227,13 +227,14 @@ function renderSkillHandout(data) {
       drivers: data.drivers,
       capabilities: data.capabilities,
       showBackLink: false,
+      showToolsAndPatterns: false,
     });
   });
 
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "skill"),
+      emojiIcon: getConceptEmoji(framework, "skill"),
       title: framework.entityDefinitions.skill.title,
       description: framework.entityDefinitions.skill.description,
     }),
@@ -261,7 +262,7 @@ function renderBehaviourHandout(data) {
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "behaviour"),
+      emojiIcon: getConceptEmoji(framework, "behaviour"),
       title: framework.entityDefinitions.behaviour.title,
       description: framework.entityDefinitions.behaviour.description,
     }),
@@ -322,7 +323,7 @@ function renderJobHandout(data) {
     {},
     // Disciplines chapter
     createChapterCover({
-      emoji: getConceptEmoji(framework, "discipline"),
+      emojiIcon: getConceptEmoji(framework, "discipline"),
       title: framework.entityDefinitions.discipline.title,
       description: framework.entityDefinitions.discipline.description,
     }),
@@ -330,7 +331,7 @@ function renderJobHandout(data) {
 
     // Grades chapter (moved before Tracks)
     createChapterCover({
-      emoji: getConceptEmoji(framework, "grade"),
+      emojiIcon: getConceptEmoji(framework, "grade"),
       title: framework.entityDefinitions.grade.title,
       description: framework.entityDefinitions.grade.description,
     }),
@@ -338,7 +339,7 @@ function renderJobHandout(data) {
 
     // Tracks chapter (moved after Grades)
     createChapterCover({
-      emoji: getConceptEmoji(framework, "track"),
+      emojiIcon: getConceptEmoji(framework, "track"),
       title: framework.entityDefinitions.track.title,
       description: framework.entityDefinitions.track.description,
     }),
@@ -393,7 +394,7 @@ function populateBrandHeader(framework) {
   header.appendChild(
     a(
       { className: "brand-title", href: "#/" },
-      `${framework.emoji} ${framework.title}`,
+      `${framework.emojiIcon} ${framework.title}`,
     ),
   );
   header.appendChild(span({ className: "brand-tag" }, framework.tag));

package/app/index.html

@@ -4,11 +4,17 @@
     <meta charset="UTF-8" />
     <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="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
     <link
       rel="stylesheet"
       href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css"
     />
+    <link rel="stylesheet" href="css/bundles/app.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">

package/app/lib/card-mappers.js

@@ -181,13 +181,40 @@ export function toolToCardConfig(tool, capabilities) {
   // Create skills list as card content
   const skillsList = createSkillsList(tool.usages, capabilities);
 
+  // Create icon element if available
+  const icon = tool.simpleIcon
+    ? createToolIcon(tool.simpleIcon, tool.name)
+    : null;
+
   return {
     title: tool.name,
     description: tool.description,
     // Docs link in header badges (upper right)
     badges: tool.url ? [createExternalLink("Docs →", tool.url)] : [],
     content: skillsList,
+    icon,
+  };
+}
+
+/**
+ * Create a tool icon element using Simple Icons CDN
+ * @param {string} slug - Simple Icons slug (e.g., 'terraform', 'docker')
+ * @param {string} name - Tool name for alt text
+ * @returns {HTMLElement}
+ */
+export function createToolIcon(slug, name) {
+  const img = document.createElement("img");
+  // Use black color for consistent monochrome appearance
+  img.src = `https://cdn.simpleicons.org/${slug}/000000`;
+  img.alt = `${name} icon`;
+  img.className = "tool-icon";
+  img.width = 28;
+  img.height = 28;
+  // Gracefully handle missing icons
+  img.onerror = () => {
+    img.style.display = "none";
   };
+  return img;
 }
 
 /**

package/app/model/agent.js

@@ -320,8 +320,11 @@ function estimateBodyDataLength(bodyData) {
   }
 
   // Array fields
-  if (bodyData.capabilities) {
-    length += bodyData.capabilities.join(", ").length;
+  if (bodyData.skillIndex) {
+    for (const skill of bodyData.skillIndex) {
+      length +=
+        skill.name.length + skill.dirname.length + skill.useWhen.length + 50;
+    }
   }
   if (bodyData.beforeMakingChanges) {
     for (const item of bodyData.beforeMakingChanges) {
@@ -491,6 +494,7 @@ function getChecklistStage(stageId) {
  * @param {Array} params.derivedSkills - Skills sorted by level
  * @param {Array} params.derivedBehaviours - Behaviours sorted by maturity
  * @param {Array} params.agentBehaviours - Agent behaviour definitions
+ * @param {Array} params.skills - All skill definitions (for agent section lookup)
  * @param {string} params.checklistMarkdown - Pre-formatted checklist markdown
  * @returns {Object} Structured profile body data
  */
@@ -503,6 +507,7 @@ function buildStageProfileBodyData({
   derivedSkills,
   derivedBehaviours,
   agentBehaviours,
+  skills,
   checklistMarkdown,
 }) {
   const name = `${humanDiscipline.specialization || humanDiscipline.name} - ${humanTrack.name}`;
@@ -532,8 +537,18 @@ function buildStageProfileBodyData({
     ? substituteTemplateVars(rawDelegation, humanDiscipline)
     : null;
 
-  // Primary capabilities from derived skills
-  const capabilities = derivedSkills.slice(0, 6).map((s) => s.skillName);
+  // Build skill index from derived skills with agent sections
+  const skillIndex = derivedSkills
+    .map((derived) => {
+      const skill = skills.find((s) => s.id === derived.skillId);
+      if (!skill?.agent) return null;
+      return {
+        name: derived.skillName,
+        dirname: skill.agent.name,
+        useWhen: skill.agent.useWhen?.trim() || "",
+      };
+    })
+    .filter(Boolean);
 
   // Operational Context - use track's roleContext (shared with human job descriptions)
   const operationalContext = humanTrack.roleContext.trim();
@@ -557,7 +572,7 @@ function buildStageProfileBodyData({
     stageDescription: stage.description,
     identity: identity.trim(),
     priority: priority ? priority.trim() : null,
-    capabilities,
+    skillIndex,
     beforeMakingChanges,
     delegation: delegation ? delegation.trim() : null,
     operationalContext,
@@ -719,6 +734,7 @@ export function generateStageAgentProfile({
     derivedSkills: agent.derivedSkills,
     derivedBehaviours: agent.derivedBehaviours,
     agentBehaviours,
+    skills,
     checklistMarkdown,
   });
 

package/app/model/checklist.js

@@ -72,7 +72,7 @@ export function deriveChecklist({
       capability: {
         id: capability.id,
         name: capability.name,
-        emoji: capability.emoji,
+        emojiIcon: capability.emojiIcon,
       },
       items: stageData.ready,
     });
@@ -94,7 +94,7 @@ export function formatChecklistMarkdown(checklist) {
   }
 
   const sections = checklist.map(({ skill, capability, items }) => {
-    const header = `**${capability.emoji} ${skill.name}**`;
+    const header = `**${capability.emojiIcon} ${skill.name}**`;
     const itemList = items.map((item) => `- [ ] ${item}`).join("\n");
     return `${header}\n\n${itemList}`;
   });

package/app/model/derivation.js

@@ -437,7 +437,7 @@ function generateJobId(discipline, grade, track = null) {
  * @param {import('./levels.js').SkillMatrixEntry[]} params.skillMatrix - Derived skill matrix for the job
  * @param {Object[]} params.capabilities - Capability definitions with responsibilities
  * @param {import('./levels.js').Discipline} params.discipline - The discipline (determines which responsibilities to use)
- * @returns {Array<{capability: string, capabilityName: string, emoji: string, responsibility: string, level: string}>}
+ * @returns {Array<{capability: string, capabilityName: string, emojiIcon: string, responsibility: string, level: string}>}
  */
 export function deriveResponsibilities({
   skillMatrix,
@@ -484,7 +484,7 @@ export function deriveResponsibilities({
       responsibilities.push({
         capability: capabilityId,
         capabilityName: capability.name,
-        emoji: capability.emoji || "💡",
+        emojiIcon: capability.emojiIcon || "💡",
         displayOrder: capability.displayOrder ?? 999,
         responsibility: responsibilityText,
         level,

package/app/model/levels.js

@@ -220,7 +220,7 @@ export function getCapabilityOrder(capabilities) {
  */
 export function getCapabilityEmoji(capabilities, capabilityId) {
   const capability = getCapabilityById(capabilities, capabilityId);
-  return capability?.emoji || "💡";
+  return capability?.emojiIcon || "💡";
 }
 
 /**
@@ -597,5 +597,5 @@ export function behaviourMaturityMeetsRequirement(actual, required) {
  * @returns {string} The emoji for the concept or default "💡"
  */
 export function getConceptEmoji(framework, concept) {
-  return framework?.entityDefinitions?.[concept]?.emoji || "💡";
+  return framework?.entityDefinitions?.[concept]?.emojiIcon || "💡";
 }

package/app/model/validation.js

@@ -1239,12 +1239,12 @@ function validateCapability(capability, index) {
       ),
     );
   }
-  if (!capability.emoji) {
+  if (!capability.emojiIcon) {
     warnings.push(
       createWarning(
         "MISSING_OPTIONAL",
-        "Capability missing emoji",
-        `${path}.emoji`,
+        "Capability missing emojiIcon",
+        `${path}.emojiIcon`,
       ),
     );
   }