@forwardimpact/pathway 0.23.0 → 0.23.2

package/README.md

@@ -7,15 +7,15 @@ teams.
 
 Pathway is the primary interface for interacting with engineering competency
 data. It provides tools for browsing career paths, generating job descriptions,
-creating agent team profiles, and preparing interviews—all from a unified web
-experience and command line.
+generating agent teams and skills, and preparing interviews—all from a unified
+web experience and command line.
 
 ## What It Does
 
 - **Web application** — Interactive browser for jobs, skills, and career paths
 - **CLI tools** — Command-line access to all functionality
-- **Agent generation** — Create VS Code Custom Agent profiles (`.agent.md`)
-- **Skill generation** — Generate Agent Skills files (`SKILL.md`)
+- **Agent teams** — Generate VS Code Custom Agent teams (`.agent.md`) and skills
+  (`SKILL.md`)
 - **Interview prep** — Build interview question sets by role
 - **Static site** — Export everything as a static site
 
@@ -29,24 +29,24 @@ npx fit-pathway serve
 npx fit-pathway skill --list
 npx fit-pathway job software_engineering senior --track=platform
 
-# Generate agent profiles
+# Generate agent teams and skills
 npx fit-pathway agent software_engineering --track=platform --output=./.github/agents
 ```
 
 ## CLI Commands
 
-| Command     | Description                  |
-| ----------- | ---------------------------- |
-| `serve`     | Start web server             |
-| `site`      | Generate static site         |
-| `init`      | Create data directory        |
-| `skill`     | Browse skills                |
-| `behaviour` | Browse behaviours            |
-| `job`       | Generate job definitions     |
-| `agent`     | Generate agent profiles      |
-| `interview` | Generate interview questions |
-| `progress`  | Analyze career progression   |
-| `questions` | Browse interview questions   |
+| Command     | Description                     |
+| ----------- | ------------------------------- |
+| `serve`     | Start web server                |
+| `site`      | Generate static site            |
+| `init`      | Create data directory           |
+| `skill`     | Browse skills                   |
+| `behaviour` | Browse behaviours               |
+| `job`       | Generate job definitions        |
+| `agent`     | Generate agent teams and skills |
+| `interview` | Generate interview questions    |
+| `progress`  | Analyze career progression      |
+| `questions` | Browse interview questions      |
 
 Use `--help` with any command for full options.
 
@@ -56,7 +56,7 @@ Use `--help` with any command for full options.
 - **Skill Browser** — View all skills with proficiency descriptions
 - **Career Progression** — Compare levels and identify growth areas
 - **Interview Prep** — Generate role-specific question sets
-- **Agent Preview** — Preview generated agent profiles
+- **Agent Preview** — Preview generated agent teams and skills
 
 ## Package Exports
 
@@ -65,4 +65,4 @@ import { formatSkillForMarkdown } from "@forwardimpact/pathway/formatters";
 import { runCommand } from "@forwardimpact/pathway/commands";
 ```
 
-See the [documentation](../../docs/pathway/index.md) for usage details.
+See the [documentation](../../website/docs/pathway/index.md) for usage details.

package/bin/fit-pathway.js

@@ -29,11 +29,14 @@
  *   --help         Show help
  */
 
-import { join, resolve } from "path";
+import { join, resolve, dirname } from "path";
 import { existsSync } from "fs";
 import { homedir } from "os";
-import { loadAllData } from "@forwardimpact/map/loader";
+import { fileURLToPath } from "url";
+import { createDataLoader } from "@forwardimpact/map/loader";
+import { validateAllData } from "@forwardimpact/map/validation";
 import { formatError } from "../src/lib/cli-output.js";
+import { createTemplateLoader } from "@forwardimpact/libtemplate";
 
 // Import command handlers
 import { runDisciplineCommand } from "../src/commands/discipline.js";
@@ -54,6 +57,9 @@ import { runInitCommand } from "../src/commands/init.js";
 import { runBuildCommand } from "../src/commands/build.js";
 import { runUpdateCommand } from "../src/commands/update.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, "..", "templates");
+
 const COMMANDS = {
   discipline: runDisciplineCommand,
   level: runLevelCommand,
@@ -117,7 +123,9 @@ Generate job definitions from discipline × level × track combinations.
 
 Usage:
   npx fit-pathway job                                  Summary with stats
+  npx fit-pathway job --track=<track>                  Summary filtered by track
   npx fit-pathway job --list                           All valid combinations
+  npx fit-pathway job --list --track=<track>            Combinations for a track
   npx fit-pathway job <discipline> <level>             Detail view (trackless)
   npx fit-pathway job <d> <l> --track=<track>          Detail view (with track)
   npx fit-pathway job <d> <l> --skills                 Plain list of skill IDs
@@ -126,15 +134,17 @@ Usage:
 
 Options:
   --track=TRACK       Track specialization (e.g., platform, forward_deployed)
+                      Also filters --list and summary modes
   --skills            Output plain list of skill IDs (for piping)
   --tools             Output plain list of tool names (for piping)
   --checklist=STAGE   Show checklist for stage handoff (plan, code)
 
 Examples:
-  npx fit-pathway job software_engineering L4
-  npx fit-pathway job software_engineering L4 --track=platform
-  npx fit-pathway job se L3 --track=platform --skills
-  npx fit-pathway job se L3 --track=platform --tools
+  npx fit-pathway job                                  # overview of all jobs
+  npx fit-pathway job --track=forward_deployed         # jobs on a specific track
+  npx fit-pathway job --list --track=forward_deployed  # list for piping
+  npx fit-pathway job software_engineering J060        # trackless job detail
+  npx fit-pathway job software_engineering J060 --track=platform  # with track
 
 ────────────────────────────────────────────────────────────────────────────────
 AGENT COMMAND
@@ -231,9 +241,7 @@ function parseArgs(args) {
     type: "full",
     compare: null,
     data: null,
-    // Shared command options
     track: null,
-    // Questions command options
     level: null,
     maturity: null,
     skill: null,
@@ -241,20 +249,15 @@ function parseArgs(args) {
     capability: null,
     format: null,
     stats: false,
-    // Job command options
     checklist: null,
     skills: false,
     tools: false,
-    // Agent command options
     output: null,
     stage: null,
     "all-stages": false,
     agent: false,
-    // Serve command options
     port: null,
-    // Init command options
     path: null,
-    // Site command options
     clean: true,
     url: null,
   };
@@ -335,54 +338,45 @@ function printHelp() {
 
 /**
  * Resolve the data directory path.
- * Resolution order:
- * 1. --data=<path> flag (explicit override)
- * 2. PATHWAY_DATA environment variable
- * 3. ~/.fit/pathway/data/ (home directory install)
- * 4. ./data/ relative to current working directory
- * 5. ./examples/ relative to current working directory
- * 6. products/map/examples/ for monorepo development
- *
  * @param {Object} options - Parsed command options
  * @returns {string} Resolved absolute path to data directory
  */
 function resolveDataPath(options) {
-  // 1. Explicit flag
   if (options.data) {
     return resolve(options.data);
   }
 
-  // 2. Environment variable
   if (process.env.PATHWAY_DATA) {
     return resolve(process.env.PATHWAY_DATA);
   }
 
-  // 3. Home directory install (~/.fit/pathway/data/)
   const homeData = join(homedir(), ".fit", "pathway", "data");
   if (existsSync(homeData)) {
     return homeData;
   }
 
-  // 4. Current working directory ./data/
+  const cwdDataPathway = join(process.cwd(), "data/pathway");
+  if (existsSync(cwdDataPathway)) {
+    return cwdDataPathway;
+  }
+
+  const cwdExamplesPathway = join(process.cwd(), "examples/pathway");
+  if (existsSync(cwdExamplesPathway)) {
+    return cwdExamplesPathway;
+  }
+
   const cwdData = join(process.cwd(), "data");
   if (existsSync(cwdData)) {
     return cwdData;
   }
 
-  // 5. Current working directory ./examples/
   const cwdExamples = join(process.cwd(), "examples");
   if (existsSync(cwdExamples)) {
     return cwdExamples;
   }
 
-  // 6. Monorepo: products/map/examples/
-  const mapExamples = join(process.cwd(), "products/map/examples");
-  if (existsSync(mapExamples)) {
-    return mapExamples;
-  }
-
   throw new Error(
-    "No data directory found. Create ./data/ or use --data=<path>",
+    "No data directory found. Create ./data/pathway/ or use --data=<path>",
   );
 }
 
@@ -398,7 +392,6 @@ async function main() {
     process.exit(0);
   }
 
-  // No command: show help
   if (!options.command) {
     printHelp();
     process.exit(0);
@@ -406,7 +399,6 @@ async function main() {
 
   const command = options.command;
 
-  // Handle init command (doesn't need data directory to exist)
   if (command === "init") {
     await runInitCommand({ options });
     process.exit(0);
@@ -414,20 +406,16 @@ async function main() {
 
   const dataDir = resolveDataPath(options);
 
-  // Handle dev command (needs data directory)
   if (command === "dev") {
     await runDevCommand({ dataDir, options });
-    // dev doesn't exit, keeps running
     return;
   }
 
-  // Handle build command (generates static site)
   if (command === "build") {
     await runBuildCommand({ dataDir, options });
     process.exit(0);
   }
 
-  // Handle update command (re-downloads bundle for local install)
   if (command === "update") {
     await runUpdateCommand({ dataDir, options });
     process.exit(0);
@@ -442,12 +430,20 @@ async function main() {
   }
 
   try {
-    const data = await loadAllData(dataDir, {
-      validate: true,
-      throwOnError: true,
+    const loader = createDataLoader();
+    const templateLoader = createTemplateLoader(TEMPLATE_DIR);
+
+    const data = await loader.loadAllData(dataDir);
+    validateAllData(data);
+
+    await handler({
+      data,
+      args: options.args,
+      options,
+      dataDir,
+      templateLoader,
+      loader,
     });
-
-    await handler({ data, args: options.args, options, dataDir });
   } catch (error) {
     console.error(formatError(error.message));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "description": "Career progression web app and CLI for exploring roles and generating agent teams",
   "license": "Apache-2.0",
   "repository": {
@@ -40,8 +40,9 @@
     "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "@forwardimpact/map": "^0.11.0",
+    "@forwardimpact/map": "^0.13.0",
     "@forwardimpact/libskill": "^3.0.0",
+    "@forwardimpact/libtemplate": "^0.2.0",
     "@forwardimpact/libui": "^1.0.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
@@ -49,5 +50,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/commands/agent.js

@@ -27,10 +27,7 @@ import { writeFile, mkdir, readFile } from "fs/promises";
 import { join, dirname } from "path";
 import { existsSync } from "fs";
 import { stringify as stringifyYaml } from "yaml";
-import {
-  loadAgentData,
-  loadSkillsWithAgentData,
-} from "@forwardimpact/map/loader";
+import { createDataLoader } from "@forwardimpact/map/loader";
 import {
   generateStageAgentProfile,
   validateAgentProfile,
@@ -50,12 +47,6 @@ import {
   formatReference,
 } from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
-import {
-  loadAgentTemplate,
-  loadSkillTemplate,
-  loadSkillInstallTemplate,
-  loadSkillReferenceTemplate,
-} from "../lib/template-loader.js";
 import { toolkitToPlainList } from "../formatters/toolkit/markdown.js";
 
 /**
@@ -209,8 +200,7 @@ function listAgentCombinations(data, agentData, verbose = false) {
         if (humanDiscipline && humanTrack) {
           const abbrev = getDisciplineAbbreviation(discipline.id);
           const agentName = `${abbrev}-${toKebabCase(track.id)}`;
-          const specName =
-            humanDiscipline.specialization || humanDiscipline.id;
+          const specName = humanDiscipline.specialization || humanDiscipline.id;
           console.log(
             `${agentName} ${discipline.id} ${track.id}, ${specName} (${humanTrack.name})`,
           );
@@ -326,10 +316,18 @@ async function writeSkills(skills, baseDir, templates) {
  * @param {Object} params.options - Command options
  * @param {string} params.dataDir - Path to data directory
  */
-export async function runAgentCommand({ data, args, options, dataDir }) {
+export async function runAgentCommand({
+  data,
+  args,
+  options,
+  dataDir,
+  templateLoader,
+  loader,
+}) {
   // Load agent-specific data
-  const agentData = await loadAgentData(dataDir);
-  const skillsWithAgent = await loadSkillsWithAgentData(dataDir);
+  const dataLoader = loader || createDataLoader();
+  const agentData = await dataLoader.loadAgentData(dataDir);
+  const skillsWithAgent = await dataLoader.loadSkillsWithAgentData(dataDir);
 
   // --list: Output clean lines for piping
   if (options.list) {
@@ -501,7 +499,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     }
 
     // Load template
-    const agentTemplate = await loadAgentTemplate(dataDir);
+    const agentTemplate = templateLoader.load("agent.template.md", dataDir);
 
     // Output to console (default) or write to files (with --output)
     if (!options.output) {
@@ -576,10 +574,16 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   }
 
   // Load templates
-  const agentTemplate = await loadAgentTemplate(dataDir);
-  const skillTemplate = await loadSkillTemplate(dataDir);
-  const installTemplate = await loadSkillInstallTemplate(dataDir);
-  const referenceTemplate = await loadSkillReferenceTemplate(dataDir);
+  const agentTemplate = templateLoader.load("agent.template.md", dataDir);
+  const skillTemplate = templateLoader.load("skill.template.md", dataDir);
+  const installTemplate = templateLoader.load(
+    "skill-install.template.sh",
+    dataDir,
+  );
+  const referenceTemplate = templateLoader.load(
+    "skill-reference.template.md",
+    dataDir,
+  );
   const skillTemplates = {
     skill: skillTemplate,
     install: installTemplate,

package/src/commands/build.js

@@ -21,8 +21,8 @@ import { join, dirname, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import { execFileSync } from "child_process";
 import Mustache from "mustache";
-import { generateAllIndexes } from "@forwardimpact/map/index-generator";
-import { loadFrameworkConfig } from "@forwardimpact/map/loader";
+import { createIndexGenerator } from "@forwardimpact/map/index-generator";
+import { createDataLoader } from "@forwardimpact/map/loader";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -85,7 +85,8 @@ export async function runBuildCommand({ dataDir, options }) {
   // Load framework config for display
   let framework;
   try {
-    framework = await loadFrameworkConfig(dataDir);
+    const loader = createDataLoader();
+    framework = await loader.loadFrameworkConfig(dataDir);
   } catch {
     framework = { emojiIcon: "🚀", title: "Engineering Pathway" };
   }
@@ -110,7 +111,8 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
 
   // Generate index files in data directory
   console.log("📇 Generating index files...");
-  await generateAllIndexes(dataDir);
+  const indexGenerator = createIndexGenerator();
+  await indexGenerator.generateAllIndexes(dataDir);
 
   // Copy app assets
   console.log("📦 Copying application files...");

package/src/commands/dev.js

@@ -9,8 +9,8 @@ import { createServer } from "http";
 import { readFile, stat } from "fs/promises";
 import { join, extname, dirname } from "path";
 import { fileURLToPath } from "url";
-import { generateAllIndexes } from "@forwardimpact/map/index-generator";
-import { loadFrameworkConfig } from "@forwardimpact/map/loader";
+import { createIndexGenerator } from "@forwardimpact/map/index-generator";
+import { createDataLoader } from "@forwardimpact/map/loader";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -108,7 +108,8 @@ export async function runDevCommand({ dataDir, options }) {
   // Load framework config for display
   let framework;
   try {
-    framework = await loadFrameworkConfig(dataDir);
+    const loader = createDataLoader();
+    framework = await loader.loadFrameworkConfig(dataDir);
   } catch {
     // Fallback if framework config fails
     framework = { emojiIcon: "🚀", title: "Engineering Pathway" };
@@ -116,7 +117,8 @@ export async function runDevCommand({ dataDir, options }) {
 
   // Generate _index.yaml files before serving
   console.log("Generating index files...");
-  await generateAllIndexes(dataDir);
+  const indexGenerator = createIndexGenerator();
+  await indexGenerator.generateAllIndexes(dataDir);
 
   const server = createServer(async (req, res) => {
     const url = new URL(req.url, `http://localhost:${port}`);

package/src/commands/discipline.js

@@ -20,7 +20,11 @@ import { formatTable } from "../lib/cli-output.js";
  * @returns {string} Formatted list line
  */
 function formatListItem(discipline) {
-  return `${discipline.id}, ${discipline.specialization || discipline.id}, ${discipline.roleTitle || discipline.id}`;
+  const type = discipline.isProfessional ? "professional" : "management";
+  const tracks = (discipline.validTracks || [])
+    .filter((t) => t !== null)
+    .join("|");
+  return `${discipline.id}, ${discipline.specialization || discipline.id}, ${type}, ${tracks || "—"}`;
 }
 
 /**
@@ -30,21 +34,14 @@ function formatListItem(discipline) {
 function formatSummary(disciplines) {
   console.log(`\n📋 Disciplines\n`);
 
-  const rows = disciplines.map((d) => [
-    d.id,
-    d.specialization || d.id,
-    d.roleTitle || d.id,
-    d.coreSkills?.length || 0,
-    d.supportingSkills?.length || 0,
-    d.broadSkills?.length || 0,
-  ]);
+  const rows = disciplines.map((d) => {
+    const type = d.isProfessional ? "Professional" : "Management";
+    const validTracks = (d.validTracks || []).filter((t) => t !== null);
+    const trackStr = validTracks.length > 0 ? validTracks.join(", ") : "—";
+    return [d.id, d.specialization || d.id, type, trackStr];
+  });
 
-  console.log(
-    formatTable(
-      ["ID", "Specialization", "Role Title", "Core", "Supporting", "Broad"],
-      rows,
-    ),
-  );
+  console.log(formatTable(["ID", "Specialization", "Type", "Tracks"], rows));
   console.log(`\nTotal: ${disciplines.length} disciplines`);
   console.log(`\nRun 'npx pathway discipline --list' for IDs and names`);
   console.log(`Run 'npx pathway discipline <id>' for details\n`);
@@ -55,8 +52,8 @@ function formatSummary(disciplines) {
  * @param {Object} viewAndContext - Contains discipline entity and context
  */
 function formatDetail(viewAndContext) {
-  const { discipline, skills, behaviours } = viewAndContext;
-  console.log(disciplineToMarkdown(discipline, { skills, behaviours }));
+  const { discipline, skills, behaviours, tracks } = viewAndContext;
+  console.log(disciplineToMarkdown(discipline, { skills, behaviours, tracks }));
 }
 
 export const runDisciplineCommand = createEntityCommand({
@@ -67,6 +64,7 @@ export const runDisciplineCommand = createEntityCommand({
     discipline: entity,
     skills: data.skills,
     behaviours: data.behaviours,
+    tracks: data.tracks,
   }),
   formatSummary,
   formatDetail,

package/src/commands/init.js

@@ -10,7 +10,17 @@ import { fileURLToPath } from "url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const examplesDir = join(__dirname, "..", "..", "examples");
+// Prefer monorepo root examples/framework/, fall back to legacy co-located examples/
+const monorepoExamplesDir = join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "..",
+  "examples",
+  "framework",
+);
+const legacyExamplesDir = join(__dirname, "..", "..", "examples");
 
 /**
  * Run the init command
@@ -31,13 +41,20 @@ export async function runInitCommand({ options }) {
     // Directory doesn't exist, proceed
   }
 
-  // Check if examples directory exists
+  // Find examples directory — monorepo root first, then legacy
+  let examplesDir;
   try {
-    await access(examplesDir);
+    await access(monorepoExamplesDir);
+    examplesDir = monorepoExamplesDir;
   } catch {
-    console.error("Error: Examples directory not found in package.");
-    console.error("This may indicate a corrupted package installation.");
-    process.exit(1);
+    try {
+      await access(legacyExamplesDir);
+      examplesDir = legacyExamplesDir;
+    } catch {
+      console.error("Error: Examples directory not found in package.");
+      console.error("This may indicate a corrupted package installation.");
+      process.exit(1);
+    }
   }
 
   // Copy example data

package/src/commands/job.js

@@ -16,13 +16,15 @@
 
 import { prepareJobDetail } from "@forwardimpact/libskill/job";
 import { jobToMarkdown } from "../formatters/job/markdown.js";
-import { generateJobTitle, generateAllJobs } from "@forwardimpact/libskill/derivation";
+import {
+  generateJobTitle,
+  generateAllJobs,
+} from "@forwardimpact/libskill/derivation";
 import { formatTable } from "../lib/cli-output.js";
 import {
   deriveChecklist,
   formatChecklistMarkdown,
 } from "@forwardimpact/libskill/checklist";
-import { loadJobTemplate } from "../lib/template-loader.js";
 import { toolkitToPlainList } from "../formatters/toolkit/markdown.js";
 
 /**
@@ -44,7 +46,13 @@ function formatJob(view, _options, entities, jobTemplate) {
  * @param {Object} params.options - Command options
  * @param {string} params.dataDir - Path to data directory
  */
-export async function runJobCommand({ data, args, options, dataDir }) {
+export async function runJobCommand({
+  data,
+  args,
+  options,
+  dataDir,
+  templateLoader,
+}) {
   const jobs = generateAllJobs({
     disciplines: data.disciplines,
     levels: data.levels,
@@ -54,9 +62,33 @@ export async function runJobCommand({ data, args, options, dataDir }) {
     validationRules: data.framework.validationRules,
   });
 
+  // Apply --track filter to list and summary modes
+  const filteredJobs = options.track
+    ? jobs.filter((j) => j.track && j.track.id === options.track)
+    : jobs;
+
+  if (options.track && filteredJobs.length === 0 && args.length === 0) {
+    const trackExists = data.tracks.some((t) => t.id === options.track);
+    if (!trackExists) {
+      console.error(`Track not found: ${options.track}`);
+      console.error(`Available: ${data.tracks.map((t) => t.id).join(", ")}`);
+    } else {
+      console.error(`No jobs found for track: ${options.track}`);
+      const trackDisciplines = data.disciplines
+        .filter((d) => d.validTracks && d.validTracks.includes(options.track))
+        .map((d) => d.id);
+      if (trackDisciplines.length > 0) {
+        console.error(
+          `Disciplines with this track: ${trackDisciplines.join(", ")}`,
+        );
+      }
+    }
+    process.exit(1);
+  }
+
   // --list: Output descriptive comma-separated lines for piping and AI agent discovery
   if (options.list) {
-    for (const job of jobs) {
+    for (const job of filteredJobs) {
       const title = generateJobTitle(job.discipline, job.level, job.track);
       if (job.track) {
         console.log(
@@ -71,29 +103,40 @@ export async function runJobCommand({ data, args, options, dataDir }) {
 
   // No args: Show summary
   if (args.length === 0) {
-    console.log(`\n💼 Jobs\n`);
+    const trackLabel = options.track ? ` — ${options.track}` : "";
+    console.log(`\n💼 Jobs${trackLabel}\n`);
 
-    // Count by discipline with name
+    // Count by discipline with name, grouped by track
     const byDiscipline = {};
-    for (const job of jobs) {
+    for (const job of filteredJobs) {
       const key = job.discipline.id;
       if (!byDiscipline[key]) {
         byDiscipline[key] = {
           name: job.discipline.specialization || job.discipline.id,
+          roleTitle: job.discipline.roleTitle || job.discipline.id,
+          type: job.discipline.isProfessional ? "Professional" : "Management",
+          tracks: new Set(),
           count: 0,
         };
       }
+      if (job.track) byDiscipline[key].tracks.add(job.track.id);
       byDiscipline[key].count++;
     }
 
     const rows = Object.entries(byDiscipline).map(([id, info]) => [
       id,
       info.name,
+      info.type,
       info.count,
+      info.tracks.size > 0 ? [...info.tracks].join(", ") : "—",
     ]);
-    console.log(formatTable(["ID", "Specialization", "Combinations"], rows));
-    console.log(`\nTotal: ${jobs.length} valid job combinations`);
-    console.log(`\nRun 'npx pathway job --list' for all combinations with titles`);
+    console.log(
+      formatTable(["ID", "Specialization", "Type", "Jobs", "Tracks"], rows),
+    );
+    console.log(`\nTotal: ${filteredJobs.length} valid job combinations`);
+    console.log(
+      `\nRun 'npx pathway job --list' for all combinations with titles`,
+    );
     console.log(
       `Run 'npx pathway job <discipline> <level> [--track=<track>]' for details\n`,
     );
@@ -102,14 +145,28 @@ export async function runJobCommand({ data, args, options, dataDir }) {
 
   // Handle job detail view - requires discipline and level
   if (args.length < 2) {
-    console.error(
-      "Usage: npx pathway job <discipline> <level> [--track=<track>]",
-    );
-    console.error("       npx pathway job --list");
-    console.error("Example: npx pathway job software_engineering L4");
-    console.error(
-      "Example: npx pathway job software_engineering L4 --track=platform",
-    );
+    // Check if the single arg is a level or track, hinting at what's missing
+    const arg = args[0];
+    const isLevel = data.levels.some((g) => g.id === arg);
+    const isTrack = data.tracks.some((t) => t.id === arg);
+    if (isLevel) {
+      console.error(
+        `Missing discipline. Usage: npx pathway job <discipline> ${arg} [--track=<track>]`,
+      );
+      console.error(
+        `Disciplines: ${data.disciplines.map((d) => d.id).join(", ")}`,
+      );
+    } else if (isTrack) {
+      console.error(`Track must be passed as a flag: --track=${arg}`);
+      console.error(
+        `Usage: npx pathway job <discipline> <level> --track=${arg}`,
+      );
+    } else {
+      console.error(
+        "Usage: npx pathway job <discipline> <level> [--track=<track>]",
+      );
+      console.error("       npx pathway job --list");
+    }
     process.exit(1);
   }
 
@@ -120,14 +177,36 @@ export async function runJobCommand({ data, args, options, dataDir }) {
     : null;
 
   if (!discipline) {
-    console.error(`Discipline not found: ${args[0]}`);
-    console.error(`Available: ${data.disciplines.map((d) => d.id).join(", ")}`);
+    // Check if args are swapped (level first, discipline second)
+    const maybeLevel = data.levels.find((g) => g.id === args[0]);
+    const maybeDiscipline = data.disciplines.find((d) => d.id === args[1]);
+    if (maybeLevel && maybeDiscipline) {
+      console.error(`Arguments are in the wrong order. Try:`);
+      console.error(
+        `  npx pathway job ${args[1]} ${args[0]}${options.track ? ` --track=${options.track}` : ""}`,
+      );
+    } else {
+      console.error(`Discipline not found: ${args[0]}`);
+      console.error(
+        `Available: ${data.disciplines.map((d) => d.id).join(", ")}`,
+      );
+    }
     process.exit(1);
   }
 
   if (!level) {
-    console.error(`Level not found: ${args[1]}`);
-    console.error(`Available: ${data.levels.map((g) => g.id).join(", ")}`);
+    // Check if the second arg is a track ID passed as positional
+    const isTrack = data.tracks.some((t) => t.id === args[1]);
+    if (isTrack) {
+      console.error(
+        `Track must be passed as a flag, not a positional argument:`,
+      );
+      console.error(`  npx pathway job ${args[0]} <level> --track=${args[1]}`);
+      console.error(`Levels: ${data.levels.map((g) => g.id).join(", ")}`);
+    } else {
+      console.error(`Level not found: ${args[1]}`);
+      console.error(`Available: ${data.levels.map((g) => g.id).join(", ")}`);
+    }
     process.exit(1);
   }
 
@@ -164,6 +243,18 @@ export async function runJobCommand({ data, args, options, dataDir }) {
         console.error(`${discipline.id} does not support tracks`);
       }
     }
+    // Check if it's a minLevel issue
+    if (discipline.minLevel) {
+      const levelIndex = data.levels.findIndex((g) => g.id === level.id);
+      const minIndex = data.levels.findIndex(
+        (g) => g.id === discipline.minLevel,
+      );
+      if (levelIndex >= 0 && minIndex >= 0 && levelIndex < minIndex) {
+        console.error(
+          `${discipline.id} requires minimum level: ${discipline.minLevel}`,
+        );
+      }
+    }
     process.exit(1);
   }
 
@@ -224,6 +315,6 @@ export async function runJobCommand({ data, args, options, dataDir }) {
   }
 
   // Load job template for description formatting
-  const jobTemplate = await loadJobTemplate(dataDir);
+  const jobTemplate = templateLoader.load("job.template.md", dataDir);
   formatJob(view, options, { discipline, level, track }, jobTemplate);
 }

package/src/commands/level.js

@@ -46,7 +46,13 @@ function formatSummary(levels, data) {
 
   console.log(
     formatTable(
-      ["ID", "Professional Title", "Management Title", "Experience", "Primary Level"],
+      [
+        "ID",
+        "Professional Title",
+        "Management Title",
+        "Experience",
+        "Primary Level",
+      ],
       rows,
     ),
   );

package/src/commands/skill.js

@@ -18,7 +18,6 @@ import { getConceptEmoji } from "@forwardimpact/map/levels";
 import { formatTable, formatError } from "../lib/cli-output.js";
 import { generateSkillMarkdown } from "@forwardimpact/libskill/agent";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
-import { loadSkillTemplate } from "../lib/template-loader.js";
 
 /**
  * Format skill summary output
@@ -69,7 +68,7 @@ function formatDetail(viewAndContext, framework) {
  * @param {Array} stages - All stage entities
  * @param {string} dataDir - Path to data directory for template loading
  */
-async function formatAgentDetail(skill, stages, dataDir) {
+async function formatAgentDetail(skill, stages, templateLoader, dataDir) {
   if (!skill.agent) {
     console.error(formatError(`Skill '${skill.id}' has no agent section`));
     console.error(`\nSkills with agent support:`);
@@ -79,7 +78,7 @@ async function formatAgentDetail(skill, stages, dataDir) {
     process.exit(1);
   }
 
-  const template = await loadSkillTemplate(dataDir);
+  const template = templateLoader.load("skill.template.md", dataDir);
   const skillMd = generateSkillMarkdown(skill, stages);
   const output = formatAgentSkill(skillMd, template);
   console.log(output);
@@ -119,7 +118,13 @@ const baseSkillCommand = createEntityCommand({
  * @param {Object} params.options - Command options
  * @param {string} params.dataDir - Path to data directory
  */
-export async function runSkillCommand({ data, args, options, dataDir }) {
+export async function runSkillCommand({
+  data,
+  args,
+  options,
+  dataDir,
+  templateLoader,
+}) {
   // Handle --agent flag for detail view
   if (options.agent && args.length > 0) {
     const [id] = args;
@@ -131,7 +136,7 @@ export async function runSkillCommand({ data, args, options, dataDir }) {
       process.exit(1);
     }
 
-    await formatAgentDetail(skill, data.stages, dataDir);
+    await formatAgentDetail(skill, data.stages, templateLoader, dataDir);
     return;
   }
 

package/src/commands/tool.js

@@ -88,7 +88,9 @@ function formatSummary(tools, totalCount) {
   if (sorted.length > 15) {
     console.log(`(showing top 15 by usage)`);
   }
-  console.log(`\nRun 'npx pathway tool --list' for all tool names and descriptions`);
+  console.log(
+    `\nRun 'npx pathway tool --list' for all tool names and descriptions`,
+  );
   console.log(`Run 'npx pathway tool <name>' for details\n`);
 }
 

package/src/commands/track.js

@@ -31,17 +31,23 @@ function formatListItem(track) {
  * @param {Object} data - Full data context
  */
 function formatSummary(tracks, data) {
-  const { framework } = data;
+  const { framework, disciplines } = data;
   const emoji = framework ? getConceptEmoji(framework, "track") : "🛤️";
 
   console.log(`\n${emoji} Tracks\n`);
 
   const rows = tracks.map((t) => {
     const modCount = Object.keys(t.skillModifiers || {}).length;
-    return [t.id, t.name, modCount];
+    const usedBy = disciplines
+      ? disciplines.filter((d) => d.validTracks && d.validTracks.includes(t.id))
+      : [];
+    const disciplineNames = usedBy
+      .map((d) => d.specialization || d.id)
+      .join(", ");
+    return [t.id, t.name, modCount, disciplineNames || "—"];
   });
 
-  console.log(formatTable(["ID", "Name", "Modifiers"], rows));
+  console.log(formatTable(["ID", "Name", "Modifiers", "Disciplines"], rows));
   console.log(`\nTotal: ${tracks.length} tracks`);
   console.log(`\nRun 'npx pathway track --list' for IDs and names`);
   console.log(`Run 'npx pathway track <id>' for details\n`);

package/src/commands/update.js

@@ -10,7 +10,7 @@ import { cp, mkdir, rm, readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
 import { homedir } from "os";
 import { execFileSync, execSync } from "child_process";
-import { loadFrameworkConfig } from "@forwardimpact/map/loader";
+import { createDataLoader } from "@forwardimpact/map/loader";
 
 const INSTALL_DIR = join(homedir(), ".fit", "pathway");
 
@@ -38,7 +38,8 @@ export async function runUpdateCommand({ dataDir: _dataDir, options }) {
   }
 
   // Load framework config to get siteUrl
-  const framework = await loadFrameworkConfig(installDataDir);
+  const loader = createDataLoader();
+  const framework = await loader.loadFrameworkConfig(installDataDir);
   const siteUrl = options.url || framework.distribution?.siteUrl;
 
   if (!siteUrl) {

package/src/formatters/discipline/markdown.js

@@ -35,16 +35,31 @@ export function disciplineListToMarkdown(disciplines) {
  * @param {Object} context - Additional context
  * @param {Array} context.skills - All skills
  * @param {Array} context.behaviours - All behaviours
+ * @param {Array} [context.tracks] - All tracks (for showing valid track names)
  * @param {boolean} [context.showBehaviourModifiers=true] - Whether to show behaviour modifiers section
  * @returns {string}
  */
 export function disciplineToMarkdown(
   discipline,
-  { skills, behaviours, showBehaviourModifiers = true } = {},
+  { skills, behaviours, tracks, showBehaviourModifiers = true } = {},
 ) {
   const view = prepareDisciplineDetail(discipline, { skills, behaviours });
+  const type = discipline.isProfessional ? "Professional" : "Management";
   const lines = [`# 📋 ${view.name}`, "", view.description, ""];
 
+  // Type and valid tracks
+  const validTracks = (discipline.validTracks || []).filter((t) => t !== null);
+  if (validTracks.length > 0) {
+    const trackNames = validTracks.map((tid) => {
+      const track = tracks?.find((t) => t.id === tid);
+      return track ? track.name : tid;
+    });
+    lines.push(`**Type:** ${type}  `);
+    lines.push(`**Valid Tracks:** ${trackNames.join(", ")}`, "");
+  } else {
+    lines.push(`**Type:** ${type}`, "");
+  }
+
   // Core skills
   if (view.coreSkills.length > 0) {
     lines.push("## Core Skills", "");

package/src/formatters/job/description.js

@@ -23,14 +23,9 @@ import { trimValue, trimFields } from "../shared.js";
  * @returns {Object} Data object ready for Mustache template
  */
 function prepareJobDescriptionData({ job, discipline, level, track }) {
-  // Build role summary from discipline - use manager version if applicable
-  const isManagement = discipline.isManagement === true;
-  let roleSummary =
-    isManagement && discipline.managementRoleSummary
-      ? discipline.managementRoleSummary
-      : discipline.professionalRoleSummary || discipline.description;
-  // Replace placeholders
+  // Build role summary from discipline
   const { roleTitle, specialization } = discipline;
+  let roleSummary = discipline.roleSummary || discipline.description;
   roleSummary = roleSummary.replace(/\{roleTitle\}/g, roleTitle);
   roleSummary = roleSummary.replace(/\{specialization\}/g, specialization);
 

package/src/formatters/track/markdown.js

@@ -44,6 +44,20 @@ export function trackToMarkdown(
   const emoji = framework ? getConceptEmoji(framework, "track") : "🛤️";
   const lines = [`# ${emoji} ${view.name}`, "", view.description, ""];
 
+  // Show which disciplines use this track
+  if (disciplines) {
+    const usedBy = disciplines.filter(
+      (d) => d.validTracks && d.validTracks.includes(track.id),
+    );
+    if (usedBy.length > 0) {
+      const names = usedBy.map(
+        (d) =>
+          `${d.specialization || d.id} (${d.isProfessional ? "professional" : "management"})`,
+      );
+      lines.push(`**Used by:** ${names.join(", ")}`, "");
+    }
+  }
+
   // Skill modifiers - show expanded skills for capabilities
   if (view.skillModifiers.length > 0) {
     lines.push("## Skill Modifiers", "");

package/src/lib/yaml-loader.js

@@ -298,9 +298,15 @@ export async function loadAgentDataBrowser(dataDir = "./data") {
     loadDisciplinesFromDir(`${dataDir}/disciplines`),
     loadTracksFromDir(`${dataDir}/tracks`),
     loadBehavioursFromDir(`${dataDir}/behaviours`),
-    tryLoadYamlFile(`${dataDir}/vscode-settings.yaml`),
-    tryLoadYamlFile(`${dataDir}/devcontainer.yaml`),
-    tryLoadYamlFile(`${dataDir}/copilot-setup-steps.yaml`),
+    tryLoadYamlFile(`${dataDir}/repository/vscode-settings.yaml`).then(
+      (r) => r ?? tryLoadYamlFile(`${dataDir}/vscode-settings.yaml`),
+    ),
+    tryLoadYamlFile(`${dataDir}/repository/devcontainer.yaml`).then(
+      (r) => r ?? tryLoadYamlFile(`${dataDir}/devcontainer.yaml`),
+    ),
+    tryLoadYamlFile(`${dataDir}/repository/copilot-setup-steps.yaml`).then(
+      (r) => r ?? tryLoadYamlFile(`${dataDir}/copilot-setup-steps.yaml`),
+    ),
   ]);
 
   return {

package/src/lib/template-loader.js

@@ -1,93 +0,0 @@
-/**
- * Template Loader
- *
- * Loads Mustache templates from the data directory with fallback to the
- * top-level templates directory. This allows users to customize agent
- * and skill templates by placing them in their data directory.
- *
- * Resolution order:
- * 1. {dataDir}/templates/{name} (user customization)
- * 2. {codebaseDir}/templates/{name} (fallback)
- */
-
-import { readFile } from "fs/promises";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { existsSync } from "fs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const CODEBASE_TEMPLATES_DIR = join(__dirname, "..", "..", "templates");
-
-/**
- * Load a template file with fallback to codebase templates
- * @param {string} templateName - Template filename (e.g., 'agent.template.md')
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Template content
- * @throws {Error} If template not found in either location
- */
-export async function loadTemplate(templateName, dataDir) {
-  // Build list of paths to try
-  const paths = [];
-  if (dataDir) {
-    paths.push(join(dataDir, "templates", templateName));
-  }
-  paths.push(join(CODEBASE_TEMPLATES_DIR, templateName));
-
-  // Try each path in order
-  for (const path of paths) {
-    if (existsSync(path)) {
-      return await readFile(path, "utf-8");
-    }
-  }
-
-  // Not found
-  throw new Error(
-    `Template '${templateName}' not found. Checked:\n` +
-      paths.map((p) => `  - ${p}`).join("\n"),
-  );
-}
-
-/**
- * Load agent profile template
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Agent template content
- */
-export async function loadAgentTemplate(dataDir) {
-  return loadTemplate("agent.template.md", dataDir);
-}
-
-/**
- * Load agent skill template
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Skill template content
- */
-export async function loadSkillTemplate(dataDir) {
-  return loadTemplate("skill.template.md", dataDir);
-}
-
-/**
- * Load skill install script template
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Install script template content
- */
-export async function loadSkillInstallTemplate(dataDir) {
-  return loadTemplate("skill-install.template.sh", dataDir);
-}
-
-/**
- * Load skill reference template
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Reference template content
- */
-export async function loadSkillReferenceTemplate(dataDir) {
-  return loadTemplate("skill-reference.template.md", dataDir);
-}
-
-/**
- * Load job description template
- * @param {string} dataDir - Path to data directory
- * @returns {Promise<string>} Job template content
- */
-export async function loadJobTemplate(dataDir) {
-  return loadTemplate("job.template.md", dataDir);
-}