@forwardimpact/pathway 0.25.20 → 0.25.22

package/src/commands/job.js

@@ -44,7 +44,11 @@ function formatJob(view, _options, entities, jobTemplate) {
  */
 function printJobList(filteredJobs) {
   for (const job of filteredJobs) {
-    const title = generateJobTitle(job.discipline, job.level, job.track);
+    const title = generateJobTitle({
+      discipline: job.discipline,
+      level: job.level,
+      track: job.track,
+    });
     if (job.track) {
       console.log(
         `${job.discipline.id} ${job.level.id} ${job.track.id}, ${title}`,

package/src/commands/skill.js

@@ -79,7 +79,7 @@ async function formatAgentDetail(skill, stages, templateLoader, dataDir) {
   }
 
   const template = templateLoader.load("skill.template.md", dataDir);
-  const skillMd = generateSkillMarkdown(skill, stages);
+  const skillMd = generateSkillMarkdown({ skillData: skill, stages });
   const output = formatAgentSkill(skillMd, template);
   console.log(output);
 }

package/src/css/pages/agent-builder.css

@@ -33,6 +33,54 @@
     gap: var(--space-xl);
   }
 
+  /* Install section — ecosystem-tool install commands shown between the
+     dropdowns and the preview cards. Uses the same surface treatment as
+     the form so the two blocks read as a matched pair. */
+  .agent-install-section {
+    background: var(--color-surface);
+    border-radius: var(--radius-lg);
+    padding: var(--space-xl);
+    box-shadow: var(--shadow-md);
+    margin-bottom: var(--space-xl);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .agent-install-header h2 {
+    margin: 0 0 var(--space-sm) 0;
+  }
+
+  .agent-install-description {
+    margin: 0;
+  }
+
+  .agent-install-commands {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .agent-install-command {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  .agent-install-command-label {
+    margin: 0;
+    font-size: var(--font-size-sm);
+    font-weight: 600;
+    color: var(--color-text-secondary);
+  }
+
+  /* Allow the command prompts inside the install section to grow beyond the
+     600px center-aligned default used on the landing hero. */
+  .agent-install-command .command-prompt {
+    max-width: none;
+    margin: 0;
+  }
+
   /* Agent section — spacing container, no surface */
   .agent-section {
     margin-bottom: var(--space-lg);

package/src/formatters/index.js

@@ -7,7 +7,6 @@
 
 // Shared utilities
 export * from "./shared.js";
-export * from "./microdata-shared.js";
 
 // Job formatters
 export { jobToMarkdown } from "./job/markdown.js";
@@ -23,15 +22,10 @@ export { progressToDOM } from "./progress/dom.js";
 
 // Driver formatters
 export { driverToDOM } from "./driver/dom.js";
-export {
-  driverListToMicrodata,
-  driverToMicrodata,
-} from "./driver/microdata.js";
 
 // Skill formatters
 export { skillListToMarkdown, skillToMarkdown } from "./skill/markdown.js";
 export { skillToDOM } from "./skill/dom.js";
-export { skillListToMicrodata, skillToMicrodata } from "./skill/microdata.js";
 
 // Behaviour formatters
 export {
@@ -39,10 +33,6 @@ export {
   behaviourToMarkdown,
 } from "./behaviour/markdown.js";
 export { behaviourToDOM } from "./behaviour/dom.js";
-export {
-  behaviourListToMicrodata,
-  behaviourToMicrodata,
-} from "./behaviour/microdata.js";
 
 // Discipline formatters
 export {
@@ -50,23 +40,14 @@ export {
   disciplineToMarkdown,
 } from "./discipline/markdown.js";
 export { disciplineToDOM } from "./discipline/dom.js";
-export {
-  disciplineListToMicrodata,
-  disciplineToMicrodata,
-} from "./discipline/microdata.js";
 
 // Level formatters
 export { levelListToMarkdown, levelToMarkdown } from "./level/markdown.js";
 export { levelToDOM } from "./level/dom.js";
-export { levelListToMicrodata, levelToMicrodata } from "./level/microdata.js";
 
 // Track formatters
 export { trackListToMarkdown, trackToMarkdown } from "./track/markdown.js";
 export { trackToDOM } from "./track/dom.js";
-export { trackListToMicrodata, trackToMicrodata } from "./track/microdata.js";
-
-// Stage formatters
-export { stageListToMicrodata, stageToMicrodata } from "./stage/microdata.js";
 
 // JSON-LD formatters
 export {

package/src/formatters/interview/shared.js

@@ -14,7 +14,9 @@ import {
   deriveDecompositionInterview,
   deriveStakeholderInterview,
 } from "@forwardimpact/libskill/interview";
-import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
+import { createJobCache } from "@forwardimpact/libskill/job-cache";
+
+const jobCache = createJobCache();
 
 /**
  * Interview type configurations
@@ -140,7 +142,7 @@ export function prepareInterviewDetail({
 }) {
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,
@@ -275,7 +277,7 @@ export function prepareInterviewBuilderPreview({
     };
   }
 
-  const title = generateJobTitle(discipline, level, track);
+  const title = generateJobTitle({ discipline, level, track });
   const totalSkills = getDisciplineSkillIds(discipline).length;
 
   return {
@@ -320,7 +322,7 @@ export function prepareAllInterviews({
   // Track is optional (null = generalist)
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,

package/src/formatters/progress/shared.js

@@ -13,7 +13,9 @@ import {
   analyzeCustomProgression,
   getNextLevel,
 } from "@forwardimpact/libskill/progression";
-import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
+import { createJobCache } from "@forwardimpact/libskill/job-cache";
+
+const jobCache = createJobCache();
 
 /**
  * Get the next level for progression
@@ -22,20 +24,7 @@ import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
  * @returns {Object|null}
  */
 export function getDefaultTargetLevel(currentLevel, levels) {
-  return getNextLevel(currentLevel, levels);
-}
-
-/**
- * Check if a job combination is valid
- * @param {Object} params
- * @param {Object} params.discipline
- * @param {Object} params.level
- * @param {Object} params.track
- * @param {Array} [params.levels] - All levels for validation
- * @returns {boolean}
- */
-export function isValidCombination({ discipline, level, track, levels }) {
-  return isValidJobCombination({ discipline, level, track, levels });
+  return getNextLevel({ level: currentLevel, levels });
 }
 
 /**
@@ -69,7 +58,7 @@ export function prepareCurrentJob({
 }) {
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,
@@ -148,8 +137,8 @@ export function prepareCareerProgressPreview({
     };
   }
 
-  const title = generateJobTitle(discipline, level, track);
-  const nextLevel = getNextLevel(level, levels);
+  const title = generateJobTitle({ discipline, level, track });
+  const nextLevel = getNextLevel({ level, levels });
 
   // Find other valid tracks for comparison (exclude current track if any)
   const validTracks = tracks.filter(
@@ -209,7 +198,7 @@ export function prepareProgressDetail({
   if (!fromDiscipline || !fromLevel) return null;
   if (!toDiscipline || !toLevel) return null;
 
-  const fromJob = getOrCreateJob({
+  const fromJob = jobCache.getOrCreate({
     discipline: fromDiscipline,
     level: fromLevel,
     track: fromTrack,
@@ -218,7 +207,7 @@ export function prepareProgressDetail({
     capabilities,
   });
 
-  const toJob = getOrCreateJob({
+  const toJob = jobCache.getOrCreate({
     discipline: toDiscipline,
     level: toLevel,
     track: toTrack,

package/src/formatters/skill/shared.js

@@ -95,11 +95,18 @@ export function prepareSkillDetail(
   if (!skill) return null;
 
   const relatedDisciplines = disciplines
-    .filter((d) => getSkillTypeForDiscipline(d, skill.id) !== null)
+    .filter(
+      (d) =>
+        getSkillTypeForDiscipline({ discipline: d, skillId: skill.id }) !==
+        null,
+    )
     .map((d) => ({
       id: d.id,
       name: d.specialization || d.name,
-      skillType: getSkillTypeForDiscipline(d, skill.id),
+      skillType: getSkillTypeForDiscipline({
+        discipline: d,
+        skillId: skill.id,
+      }),
     }));
 
   const relatedTracks = tracks

package/src/formatters/track/shared.js

@@ -88,7 +88,10 @@ export function prepareTrackDetail(track, { skills, behaviours }) {
   const skillModifiers = track.skillModifiers
     ? Object.entries(track.skillModifiers).map(([key, modifier]) => {
         if (isCapability(key)) {
-          const capabilitySkills = getSkillsByCapability(skills, key);
+          const capabilitySkills = getSkillsByCapability({
+            skills,
+            capability: key,
+          });
           return {
             id: key,
             name: key.charAt(0).toUpperCase() + key.slice(1),

package/src/pages/agent-builder-install.js

@@ -0,0 +1,117 @@
+/**
+ * Agent builder install section
+ *
+ * Surfaces the ecosystem-tool install commands (Microsoft APM and
+ * `npx skills`) for the currently selected discipline/track pack. The packs
+ * themselves are emitted by `fit-pathway build` when
+ * `framework.distribution.siteUrl` is configured — see spec 320 and
+ * `products/pathway/src/commands/build-packs.js`. The pack name derivation
+ * here must stay in sync with that generator so the command points at an
+ * archive that actually exists on the deployed site.
+ */
+
+import { code, div, h2, p, section } from "../lib/render.js";
+import {
+  getDisciplineAbbreviation,
+  toKebabCase,
+} from "@forwardimpact/libskill/agent";
+import { createCommandPrompt } from "../components/command-prompt.js";
+
+/** Stable id for the install section heading (for aria-labelledby). */
+const INSTALL_HEADING_ID = "agent-builder-install-heading";
+
+/**
+ * Derive the pack archive name for a discipline/track combination.
+ * Must match `build-packs.js` → `${abbrev}-${toKebabCase(track.id)}`.
+ * @param {{id: string}} discipline
+ * @param {{id: string}} track
+ * @returns {string}
+ */
+export function getPackName(discipline, track) {
+  return `${getDisciplineAbbreviation(discipline.id)}-${toKebabCase(track.id)}`;
+}
+
+/**
+ * Normalize a site URL by stripping a trailing slash. Matches the
+ * normalization applied by `generatePacks` so the displayed URL lines up
+ * with the manifest entries.
+ * @param {string} siteUrl
+ * @returns {string}
+ */
+function normalizeSiteUrl(siteUrl) {
+  return siteUrl.replace(/\/$/, "");
+}
+
+/**
+ * Build the `apm install` command for a specific pack archive. Targets the
+ * direct archive URL (rather than a registry-style shorthand) because it is
+ * the most durable path through APM's evolving resolution logic and matches
+ * the URL listed in the generated `apm.yml` manifest.
+ * @param {string} siteUrl
+ * @param {string} packName
+ * @returns {string}
+ */
+export function getApmInstallCommand(siteUrl, packName) {
+  return `apm install ${normalizeSiteUrl(siteUrl)}/packs/${packName}.tar.gz`;
+}
+
+/**
+ * Build the `npx skills add` command that discovers the published pack
+ * registry at `<siteUrl>/.well-known/agent-skills/index.json`.
+ * @param {string} siteUrl
+ * @returns {string}
+ */
+export function getSkillsAddCommand(siteUrl) {
+  return `npx skills add ${normalizeSiteUrl(siteUrl)}`;
+}
+
+/**
+ * Render the install section for the selected agent combination. Returns
+ * `null` when no site URL is configured (no packs have been published, so
+ * there is nothing meaningful to install) so the caller can skip rendering.
+ * @param {Object} params
+ * @param {{id: string}} params.discipline - Selected human discipline
+ * @param {{id: string}} params.track - Selected human track
+ * @param {string|undefined} params.siteUrl - Framework distribution site URL
+ * @returns {HTMLElement|null}
+ */
+export function createInstallSection({ discipline, track, siteUrl }) {
+  if (!siteUrl) return null;
+
+  const packName = getPackName(discipline, track);
+  const apmCommand = getApmInstallCommand(siteUrl, packName);
+  const skillsCommand = getSkillsAddCommand(siteUrl);
+
+  return section(
+    {
+      className: "agent-install-section",
+      "aria-labelledby": INSTALL_HEADING_ID,
+    },
+    div(
+      { className: "agent-install-header" },
+      h2({ id: INSTALL_HEADING_ID }, "📦 Install This Agent Team"),
+      p(
+        { className: "text-muted agent-install-description" },
+        "Install the pre-built pack for this discipline × track combination " +
+          "directly through an ecosystem package manager. The pack contains " +
+          "the same stage agents, skills, team instructions, and Claude Code " +
+          "settings shown below — installed into your project's ",
+        code({}, ".claude/"),
+        " directory.",
+      ),
+    ),
+    div(
+      { className: "agent-install-commands" },
+      div(
+        { className: "agent-install-command" },
+        p({ className: "agent-install-command-label" }, "Microsoft APM"),
+        createCommandPrompt(apmCommand),
+      ),
+      div(
+        { className: "agent-install-command" },
+        p({ className: "agent-install-command-label" }, "npx skills"),
+        createCommandPrompt(skillsCommand),
+      ),
+    ),
+  );
+}

package/src/pages/agent-builder-preview.js

@@ -10,8 +10,8 @@ import {
   deriveStageAgent,
   generateSkillMarkdown,
   deriveAgentSkills,
-  deriveToolkit,
-} from "@forwardimpact/libskill";
+} from "@forwardimpact/libskill/agent";
+import { deriveToolkit } from "@forwardimpact/libskill/toolkit";
 import { getStageEmoji } from "../formatters/stage/shared.js";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import {
@@ -115,7 +115,7 @@ function deriveSkillData(context) {
   const skillFiles = derivedSkills
     .map((d) => skills.find((s) => s.id === d.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMarkdown(skill, stages));
+    .map((skill) => generateSkillMarkdown({ skillData: skill, stages }));
 
   const toolkit = deriveToolkit({
     skillMatrix: derivedSkills,

package/src/pages/agent-builder.js

@@ -18,7 +18,7 @@ import {
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { loadAgentDataBrowser } from "../lib/yaml-loader.js";
-import { deriveReferenceLevel } from "@forwardimpact/libskill";
+import { deriveReferenceLevel } from "@forwardimpact/libskill/agent";
 import {
   createSelectWithValue,
   createDisciplineSelect,
@@ -30,6 +30,7 @@ import {
   createSingleStagePreview,
   createHelpSection,
 } from "./agent-builder-preview.js";
+import { createInstallSection } from "./agent-builder-install.js";
 
 /** All stages option value */
 const ALL_STAGES_VALUE = "all";
@@ -79,6 +80,7 @@ async function getTemplates() {
  */
 export async function renderAgentBuilder() {
   const { data } = getState();
+  const siteUrl = data.framework?.distribution?.siteUrl;
 
   // Show loading state
   render(
@@ -260,8 +262,27 @@ export async function renderAgentBuilder() {
       templates,
     };
 
+    // Install section (ecosystem-tool install commands) — appears above the
+    // preview cards so the install action is visible before users scroll
+    // through the generated files. Only rendered when the framework has a
+    // published distribution site URL, since the packs only exist at that
+    // URL after a `fit-pathway build`. Must come after the stage-validity
+    // guard below so an invalid stage id (e.g. from a stale bookmark) does
+    // not pair the install card with a "Stage not found" error.
+    function appendInstallSection() {
+      const installSection = createInstallSection({
+        discipline: humanDiscipline,
+        track: humanTrack,
+        siteUrl,
+      });
+      if (installSection) {
+        previewContainer.appendChild(installSection);
+      }
+    }
+
     // Generate preview based on stage selection
     if (stage === ALL_STAGES_VALUE) {
+      appendInstallSection();
       previewContainer.appendChild(createAllStagesPreview(context));
     } else {
       const stageObj = stages.find((s) => s.id === stage);
@@ -274,6 +295,7 @@ export async function renderAgentBuilder() {
         );
         return;
       }
+      appendInstallSection();
       previewContainer.appendChild(createSingleStagePreview(context, stageObj));
     }
   }

package/src/pages/progress.js

@@ -16,8 +16,8 @@ import {
   prepareCurrentJob,
   prepareCustomProgression,
   getDefaultTargetLevel,
-  isValidCombination,
 } from "../formatters/progress/shared.js";
+import { isValidJobCombination } from "@forwardimpact/libskill/derivation";
 import { buildComparisonResult } from "./progress-comparison.js";
 
 /**
@@ -188,7 +188,7 @@ function createComparisonSelectorsSection({
     for (const level of data.levels) {
       // Check trackless combination
       if (
-        isValidCombination({ discipline: selectedDisc, level, track: null })
+        isValidJobCombination({ discipline: selectedDisc, level, track: null })
       ) {
         if (!validLevels.find((g) => g.id === level.id)) {
           validLevels.push(level);
@@ -197,7 +197,7 @@ function createComparisonSelectorsSection({
       }
       // Check each track combination
       for (const track of data.tracks) {
-        if (isValidCombination({ discipline: selectedDisc, level, track })) {
+        if (isValidJobCombination({ discipline: selectedDisc, level, track })) {
           if (!validLevels.find((g) => g.id === level.id)) {
             validLevels.push(level);
           }

package/src/pages/skill.js

@@ -11,7 +11,7 @@ import { prepareSkillsList } from "../formatters/skill/shared.js";
 import { skillToDOM } from "../formatters/skill/dom.js";
 import { skillToCardConfig } from "../lib/card-mappers.js";
 import { getCapabilityEmoji, getConceptEmoji } from "@forwardimpact/map/levels";
-import { generateSkillMarkdown } from "@forwardimpact/libskill";
+import { generateSkillMarkdown } from "@forwardimpact/libskill/agent";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 
 /** @type {string|null} Cached skill template */
@@ -101,7 +101,10 @@ export async function renderSkillDetail(params) {
   let agentSkillContent;
   if (skill.agent) {
     const template = await getSkillTemplate();
-    const skillData = generateSkillMarkdown(skill, data.stages);
+    const skillData = generateSkillMarkdown({
+      skillData: skill,
+      stages: data.stages,
+    });
     agentSkillContent = formatAgentSkill(skillData, template);
   }
 

package/src/formatters/behaviour/microdata.js

@@ -1,106 +0,0 @@
-/**
- * Behaviour formatting for microdata HTML output
- *
- * Generates clean, class-less HTML with microdata aligned with behaviour.schema.json
- * RDF vocab: https://www.forwardimpact.team/schema/rdf/
- */
-
-import {
-  openTag,
-  prop,
-  propRaw,
-  metaTag,
-  section,
-  dl,
-  ul,
-  escapeHtml,
-  formatLevelName,
-  htmlDocument,
-} from "../microdata-shared.js";
-import { prepareBehavioursList, prepareBehaviourDetail } from "./shared.js";
-
-/**
- * Format behaviour list as microdata HTML
- * @param {Array} behaviours - Raw behaviour entities
- * @returns {string} HTML with microdata
- */
-export function behaviourListToMicrodata(behaviours) {
-  const { items } = prepareBehavioursList(behaviours);
-
-  const content = items
-    .map(
-      (
-        behaviour,
-      ) => `${openTag("article", { itemtype: "Behaviour", itemid: `#${behaviour.id}` })}
-${prop("h2", "name", behaviour.name)}
-${prop("p", "description", behaviour.truncatedDescription)}
-</article>`,
-    )
-    .join("\n");
-
-  return htmlDocument(
-    "Behaviours",
-    `<main>
-<h1>Behaviours</h1>
-${content}
-</main>`,
-  );
-}
-
-/**
- * Format behaviour detail as microdata HTML
- * @param {Object} behaviour - Raw behaviour entity
- * @param {Object} context - Additional context
- * @param {Array} context.drivers - All drivers
- * @returns {string} HTML with microdata
- */
-export function behaviourToMicrodata(behaviour, { drivers }) {
-  const view = prepareBehaviourDetail(behaviour, { drivers });
-
-  if (!view) return "";
-
-  const sections = [];
-
-  // Maturity descriptions - uses MaturityDescriptions itemtype
-  const maturityPairs = Object.entries(view.maturityDescriptions).map(
-    ([maturity, desc]) => ({
-      term: formatLevelName(maturity),
-      definition: desc,
-      itemprop: `${maturity.replace(/_([a-z])/g, (_, c) => c.toUpperCase())}Description`,
-    }),
-  );
-  sections.push(
-    section(
-      "Maturity Levels",
-      `${openTag("div", { itemtype: "MaturityDescriptions", itemprop: "maturityDescriptions" })}
-${dl(maturityPairs)}
-</div>`,
-      2,
-    ),
-  );
-
-  // Related drivers
-  if (view.relatedDrivers.length > 0) {
-    const driverItems = view.relatedDrivers.map(
-      (d) => `<a href="#${escapeHtml(d.id)}">${escapeHtml(d.name)}</a>`,
-    );
-    sections.push(section("Linked to Drivers", ul(driverItems), 2));
-  }
-
-  const body = `<main>
-${openTag("article", { itemtype: "Behaviour", itemid: `#${view.id}` })}
-${prop("h1", "name", view.name)}
-${metaTag("id", view.id)}
-${propRaw(
-  "div",
-  "human",
-  `${openTag("div", { itemtype: "BehaviourHumanSection" })}
-${prop("p", "description", view.description)}
-${sections.join("\n")}
-</div>`,
-)}
-</article>
-</main>`;
-
-  return htmlDocument(view.name, body);
-}