@lucasviola/specwiki 1.0.1 → 1.1.0

package/dist/output/html/nav-grouping.js

@@ -1,10 +1,19 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-const BMAD_HELP_PATH = "_bmad/_config/bmad-help.csv";
+import { loadNavGroupingContext, } from "./nav-grouping-catalog.js";
+export { loadNavGroupingContext };
+const HYBRID_GROUPS = [
+    { key: "your-team", label: "Your team" },
+    { key: "analysis", label: "Analysis" },
+    { key: "planning", label: "Planning" },
+    { key: "solutioning", label: "Solutioning" },
+    { key: "implementation", label: "Implementation" },
+    { key: "core-utilities", label: "Core utilities" },
+    { key: "deprecated", label: "Deprecated" },
+    { key: "uncatalogued", label: "Uncatalogued" },
+];
 const CATEGORY_PATH_PREFIXES = {
-    "agent-skills": ".agents/skills/",
-    "cursor-skills": ".cursor/skills/",
     "cursor-rules": ".cursor/rules/",
+    "cursor-skills": ".cursor/skills/",
+    "agent-skills": ".agents/skills/",
     "bmad-output": "_bmad-output/",
     specs: "specs/",
     spec: "spec/",
@@ -14,595 +23,469 @@ const CATEGORY_PATH_PREFIXES = {
     plans: "docs/plans/",
     requirements: "requirements/",
     github: ".github/",
+    root: "",
 };
 const FOLDER_LABELS = {
+    planning: "Planning",
     "planning-artifacts": "Planning",
     "implementation-artifacts": "Implementation Stories",
+    "implementation-stories": "Implementation Stories",
+    "epic-context": "Epic Context",
     discovery: "Discovery",
     research: "Research",
-    prd: "PRD",
-    architecture: "Architecture",
-    readiness: "Readiness",
-    epics: "Epics",
-};
-const PHASE_GROUPS = {
-    "1-analysis": { key: "phase-analysis", label: "Analysis", sortOrder: 1 },
-    "2-planning": { key: "phase-planning", label: "Planning", sortOrder: 2 },
-    "3-solutioning": {
-        key: "phase-solutioning",
-        label: "Solutioning",
-        sortOrder: 3,
-    },
-    "4-implementation": {
-        key: "phase-implementation",
-        label: "Implementation",
-        sortOrder: 4,
-    },
-};
-const YOUR_TEAM_GROUP = {
-    key: "your-team",
-    label: "Your team",
-    sortOrder: 0,
-};
-const CORE_UTILITIES_GROUP = {
-    key: "core-utilities",
-    label: "Core utilities",
-    sortOrder: 5,
-};
-const DEPRECATED_GROUP = {
-    key: "deprecated",
-    label: "Deprecated",
-    sortOrder: 6,
-};
-const UNCATALOGUED_GROUP = {
-    key: "uncatalogued",
-    label: "Uncatalogued",
-    sortOrder: 7,
+    other: "Other",
 };
-const PROJECT_DOCS_GROUP = {
-    key: "project-docs",
-    label: "Project docs",
-    sortOrder: 0,
-};
-export async function loadNavGroupingContext(projectRoot) {
-    if (!projectRoot) {
-        return { bmadCatalog: null };
+const STORY_FILENAME_PATTERN = /^(\d+)-(\d+)-/;
+function storyNumbers(sourcePath) {
+    const filename = sourcePath.split("/").pop() ?? sourcePath;
+    const match = filename.match(STORY_FILENAME_PATTERN);
+    return {
+        epic: parseInt(match?.[1] ?? "0", 10),
+        story: parseInt(match?.[2] ?? "0", 10),
+    };
+}
+let subgroupOrderCounter = 0;
+export function buildCategoryNavSubgroups(pages, options) {
+    subgroupOrderCounter = 0;
+    if (options.categoryKey === "agent-skills" &&
+        options.context?.loaded === true) {
+        return buildHybridAgentSkillsGrouping(pages, options);
     }
-    const csvPath = path.join(projectRoot, BMAD_HELP_PATH);
-    try {
-        const csvContent = await fs.readFile(csvPath, "utf-8");
-        const catalog = await parseBmadHelpCsv(csvContent, projectRoot);
-        return { bmadCatalog: catalog };
+    const rootPages = [];
+    const rootChildren = new Map();
+    for (const page of pages) {
+        const navPage = toNavPage(page);
+        const segments = resolveSubgroupSegments(page.sourcePath, options.categoryKey);
+        if (segments.length === 0) {
+            rootPages.push(navPage);
+            continue;
+        }
+        insertIntoTree(rootChildren, segments, navPage);
     }
-    catch {
-        return { bmadCatalog: null };
+    if (options.categoryKey === "bmad-output") {
+        sortImplementationStoryPages(rootChildren);
     }
+    const subgroups = finalizeSubgroups(rootChildren, options);
+    const promotedPages = [...rootPages, ...subgroups.rootPromoted];
+    const visibleSubgroups = subgroups.subgroups;
+    const hasSubgroups = visibleSubgroups.length > 0;
+    return {
+        pages: promotedPages,
+        subgroups: visibleSubgroups,
+        hasSubgroups,
+    };
 }
-export function buildCategoryNavSubgroups(category, pages, context, activePageSlug) {
-    const assignments = pages.map((page) => ({
-        page,
-        assignment: assignPageGroups(page, category, context),
-    }));
-    const hasGrouping = assignments.some(({ assignment }) => assignment.segments.length > 0);
-    if (!hasGrouping) {
-        return {
-            subgroups: [],
-            pages: sortNavPages(assignments.map(({ page, assignment }) => toNavPage(page, assignment.displayTitle))),
-        };
-    }
-    const tree = buildTreeFromAssignments(assignments);
-    const flattened = flattenSingletonSubgroups(tree);
-    const promoted = promoteSingletonPages(flattened);
-    const withState = applyNavSubgroupState(promoted.subgroups, category, activePageSlug);
-    if (withState.length === 0 && promoted.pages.length > 0) {
-        return {
-            subgroups: [],
-            pages: sortNavPages(promoted.pages),
-        };
+function buildHybridAgentSkillsGrouping(pages, options) {
+    const skillsById = options.context?.skillsById ?? new Map();
+    /** phase → skillId ("" for orphans) → wiki pages */
+    const buckets = new Map();
+    for (const page of pages) {
+        const skillId = agentSkillIdFromPath(page.sourcePath);
+        const entry = skillId ? skillsById.get(skillId) : undefined;
+        const groupKey = resolveHybridGroupKey(entry);
+        const skillKey = skillId ?? "";
+        let phaseSkills = buckets.get(groupKey);
+        if (!phaseSkills) {
+            phaseSkills = new Map();
+            buckets.set(groupKey, phaseSkills);
+        }
+        const list = phaseSkills.get(skillKey) ?? [];
+        list.push(page);
+        phaseSkills.set(skillKey, list);
     }
-    if (withState.length === 1 && withState[0].pages.length === 0) {
-        return {
-            subgroups: [],
-            pages: sortNavPages([
-                ...promoted.pages,
-                ...withState[0].subgroups.flatMap(collectPages),
-            ]),
+    const rootChildren = new Map();
+    for (const group of HYBRID_GROUPS) {
+        const phaseSkills = buckets.get(group.key);
+        if (!phaseSkills || phaseSkills.size === 0) {
+            continue;
+        }
+        const phaseNode = {
+            key: group.key,
+            label: group.label,
+            pages: [],
+            children: new Map(),
+            order: subgroupOrderCounter++,
         };
+        const skillEntries = [...phaseSkills.entries()].sort(([idA, pagesA], [idB, pagesB]) => {
+            const labelA = resolveHybridSkillLabel(idA, pagesA[0], skillsById.get(idA));
+            const labelB = resolveHybridSkillLabel(idB, pagesB[0], skillsById.get(idB));
+            return labelA.localeCompare(labelB, undefined, { sensitivity: "base" });
+        });
+        for (const [skillKey, skillPages] of skillEntries) {
+            const entry = skillKey ? skillsById.get(skillKey) : undefined;
+            // Paths outside .agents/skills/ stay as direct Uncatalogued leaves.
+            if (!skillKey) {
+                for (const page of skillPages) {
+                    phaseNode.pages.push(toNavPage(page));
+                }
+                continue;
+            }
+            const skillLabel = resolveHybridSkillLabel(skillKey, skillPages[0], entry);
+            // Single-page skills: L4 title on the phase leaf (no L2 wrapper).
+            if (skillPages.length === 1) {
+                phaseNode.pages.push(toNavPage(skillPages[0], resolveAgentSkillTitle(skillPages[0], entry)));
+                continue;
+            }
+            const nestedPages = skillPages
+                .map((page) => toNavPage(page))
+                .sort((a, b) => a.title.localeCompare(b.title, undefined, { sensitivity: "base" }));
+            phaseNode.children.set(skillKey, {
+                key: `${group.key}/${skillKey}`,
+                label: skillLabel,
+                pages: nestedPages,
+                children: new Map(),
+                order: subgroupOrderCounter++,
+            });
+        }
+        phaseNode.pages.sort((a, b) => a.title.localeCompare(b.title, undefined, { sensitivity: "base" }));
+        rootChildren.set(group.key, phaseNode);
     }
+    const subgroups = finalizeSubgroups(rootChildren, options);
     return {
-        subgroups: withState,
-        pages: sortNavPages(promoted.pages),
+        pages: subgroups.rootPromoted,
+        subgroups: subgroups.subgroups,
+        hasSubgroups: subgroups.subgroups.length > 0,
     };
 }
-export function resolveNavSubgroupLabel(page, category, context) {
-    const assignment = assignPageGroups(page, category, context);
-    if (assignment.segments.length === 0) {
-        return undefined;
+function resolveHybridSkillLabel(skillId, page, entry) {
+    if (!skillId) {
+        return page.title;
     }
-    return assignment.segments.map((segment) => segment.label).join(" › ");
-}
-function assignPageGroups(page, category, context) {
-    if (category === "agent-skills" && context.bmadCatalog) {
-        const bmadAssignment = assignAgentSkillGroups(page, context.bmadCatalog);
-        if (bmadAssignment) {
-            return bmadAssignment;
-        }
+    if (entry?.isAgent && entry.agentName && entry.agentTitle) {
+        return resolveAgentSkillTitle(page, entry);
     }
-    if (category === "bmad-output") {
-        const bmadOutputAssignment = assignBmadOutputGroups(page);
-        if (bmadOutputAssignment) {
-            return bmadOutputAssignment;
-        }
+    if (entry?.displayName) {
+        return entry.displayName;
     }
-    return assignPathSegmentGroups(page, category);
+    // Stable label for uncatalogued multi-page skills (not first-page wiki title).
+    return humanizeFolderLabel(skillId, [skillId]);
 }
-function assignAgentSkillGroups(page, catalog) {
-    const skillFolder = extractSkillFolder(page.sourcePath);
-    if (!skillFolder) {
+function agentSkillIdFromPath(sourcePath) {
+    const normalized = normalizePath(sourcePath);
+    const prefix = ".agents/skills/";
+    if (!normalized.startsWith(prefix)) {
         return null;
     }
-    const agent = catalog.agents.get(skillFolder);
-    if (agent) {
-        const displayTitle = formatAgentTitle(agent);
-        return {
-            segments: [YOUR_TEAM_GROUP],
-            pageSortKey: `00-${agent.name.toLowerCase()}`,
-            displayTitle,
-        };
+    const skillId = normalized.slice(prefix.length).split("/")[0];
+    return skillId || null;
+}
+function resolveHybridGroupKey(entry) {
+    if (entry?.isAgent) {
+        return "your-team";
     }
-    const entry = catalog.skills.get(skillFolder);
-    if (!entry) {
-        return {
-            segments: [UNCATALOGUED_GROUP],
-            pageSortKey: `99-${page.title.toLowerCase()}`,
-        };
+    if (entry?.description?.toLowerCase().includes("deprecated")) {
+        return "deprecated";
     }
-    if (entry.deprecated) {
-        return {
-            segments: [DEPRECATED_GROUP],
-            pageSortKey: `98-${entry.displayName.toLowerCase()}`,
-            displayTitle: entry.displayName,
-        };
+    switch (entry?.phase) {
+        case "1-analysis":
+            return "analysis";
+        case "2-planning":
+            return "planning";
+        case "3-solutioning":
+            return "solutioning";
+        case "4-implementation":
+            return "implementation";
+        default:
+            break;
+    }
+    if (entry?.module === "Core" || entry?.phase === "anytime") {
+        return "core-utilities";
+    }
+    if (entry?.inCsv) {
+        return "core-utilities";
+    }
+    return "uncatalogued";
+}
+function resolveAgentSkillTitle(page, entry) {
+    if (entry?.isAgent && entry.agentName && entry.agentTitle) {
+        return entry.agentIcon
+            ? `${entry.agentIcon} ${entry.agentName} — ${entry.agentTitle}`
+            : `${entry.agentName} — ${entry.agentTitle}`;
     }
-    const segment = resolveSkillPhaseGroup(entry);
+    if (entry?.displayName) {
+        return entry.displayName;
+    }
+    return page.title;
+}
+function toNavPage(page, titleOverride) {
     return {
-        segments: [segment],
-        pageSortKey: `${String(segment.sortOrder).padStart(2, "0")}-${entry.displayName.toLowerCase()}`,
-        displayTitle: entry.displayName,
+        title: titleOverride ?? page.title,
+        slug: page.slug,
+        href: `${page.slug}.html`,
+        sourcePath: page.sourcePath,
     };
 }
-function resolveSkillPhaseGroup(entry) {
-    if (entry.module === "Core" || entry.phase === "anytime") {
-        return CORE_UTILITIES_GROUP;
+function normalizePath(sourcePath) {
+    return sourcePath.replace(/\\/g, "/");
+}
+function resolveSubgroupSegments(sourcePath, categoryKey) {
+    const normalized = normalizePath(sourcePath);
+    if (categoryKey === "bmad-output") {
+        const bmadSegments = resolveBmadOutputSegments(normalized);
+        if (bmadSegments !== null) {
+            return bmadSegments;
+        }
     }
-    return PHASE_GROUPS[entry.phase] ?? UNCATALOGUED_GROUP;
+    return resolveL0Segments(normalized, categoryKey);
 }
-function assignBmadOutputGroups(page) {
-    const normalized = page.sourcePath.replace(/\\/g, "/");
+function resolveBmadOutputSegments(normalized) {
     if (!normalized.startsWith("_bmad-output/")) {
         return null;
     }
-    const remainder = normalized.slice("_bmad-output/".length);
-    const basename = path.posix.basename(remainder);
-    if (remainder.startsWith("planning-artifacts/")) {
-        const relativeDir = path.posix.dirname(remainder);
-        const dirParts = relativeDir.split("/").filter(Boolean);
-        const planning = {
-            key: "planning",
-            label: "Planning",
-            sortOrder: 0,
-        };
-        if (dirParts.length <= 1) {
-            return {
-                segments: [planning],
-                pageSortKey: basename,
-            };
+    const relative = normalized.slice("_bmad-output/".length);
+    const dirParts = relative.split("/");
+    const filename = dirParts.pop() ?? "";
+    if (dirParts[0] === "planning-artifacts" || dirParts[0] === "planning") {
+        if (dirParts[0] === "planning-artifacts") {
+            const childKey = dirParts[1] ?? "other";
+            return ["planning", childKey];
         }
-        const subKey = dirParts.slice(1).join("/");
-        const subLabel = labelForPathSegment(dirParts[1]);
-        return {
-            segments: [
-                planning,
-                {
-                    key: `planning-${subKey}`,
-                    label: subLabel,
-                    sortOrder: 0,
-                },
-            ],
-            pageSortKey: basename,
-        };
-    }
-    if (remainder.startsWith("implementation-artifacts/")) {
-        const implementation = {
-            key: "implementation",
-            label: "Implementation Stories",
-            sortOrder: 1,
-        };
-        if (basename.startsWith("epic-")) {
-            return {
-                segments: [
-                    {
-                        key: "epic-context",
-                        label: "Epic Context",
-                        sortOrder: 2,
-                    },
-                ],
-                pageSortKey: basename,
-            };
+        if (dirParts.length === 1) {
+            return ["planning"];
         }
-        const epicMatch = basename.match(/^(\d+)-(\d+)-/);
-        if (epicMatch) {
-            const epicNumber = epicMatch[1];
-            return {
-                segments: [
-                    implementation,
-                    {
-                        key: `epic-${epicNumber}`,
-                        label: `Epic ${epicNumber}`,
-                        sortOrder: Number.parseInt(epicNumber, 10),
-                    },
-                ],
-                pageSortKey: basename,
-            };
-        }
-        return {
-            segments: [
-                implementation,
-                {
-                    key: "other-stories",
-                    label: "Other Stories",
-                    sortOrder: 999,
-                },
-            ],
-            pageSortKey: basename,
-        };
+        return ["planning", dirParts[1]];
     }
-    return assignPathSegmentGroups(page, "bmad-output");
-}
-function assignPathSegmentGroups(page, category) {
-    const normalized = page.sourcePath.replace(/\\/g, "/");
-    const prefix = CATEGORY_PATH_PREFIXES[category];
-    let remainder = normalized;
-    if (prefix && normalized.startsWith(prefix)) {
-        remainder = normalized.slice(prefix.length);
-    }
-    const dirname = path.posix.dirname(remainder);
-    if (dirname === ".") {
-        if (category === "other" && normalized.includes("/")) {
-            const topSegment = normalized.split("/")[0];
-            return {
-                segments: [
-                    {
-                        key: topSegment,
-                        label: labelForPathSegment(topSegment),
-                        sortOrder: 0,
-                    },
-                ],
-                pageSortKey: normalized,
-            };
+    if (dirParts[0] === "implementation-artifacts") {
+        if (dirParts.length === 1 && filename.startsWith("epic-")) {
+            return ["epic-context"];
         }
-        if (category === "other" || category === "root") {
-            return {
-                segments: category === "other" ? [PROJECT_DOCS_GROUP] : [],
-                pageSortKey: page.title.toLowerCase(),
-            };
+        const storyMatch = filename.match(STORY_FILENAME_PATTERN);
+        if (storyMatch) {
+            const epicNum = storyMatch[1];
+            return ["implementation-stories", `epic-${epicNum}`];
         }
-        return {
-            segments: [],
-            pageSortKey: page.title.toLowerCase(),
-        };
-    }
-    const dirParts = dirname.split("/").filter(Boolean);
-    const segments = dirParts.slice(0, 2).map((part, index) => ({
-        key: dirParts.slice(0, index + 1).join("/"),
-        label: labelForPathSegment(part),
-        sortOrder: 0,
-    }));
-    return {
-        segments,
-        pageSortKey: normalized,
-    };
-}
-function buildTreeFromAssignments(assignments) {
-    const roots = new Map();
-    for (const { page, assignment } of assignments) {
-        if (assignment.segments.length === 0) {
-            const rootKey = "__root_pages__";
-            const root = roots.get(rootKey) ?? createMutableSubgroup(rootKey, "", 0);
-            root.pages.push(toNavPage(page, assignment.displayTitle));
-            roots.set(rootKey, root);
-            continue;
-        }
-        let level = roots;
-        let parent;
-        for (const [index, segment] of assignment.segments.entries()) {
-            const existing = level.get(segment.key);
-            const node = existing ??
-                createMutableSubgroup(segment.key, segment.label, segment.sortOrder);
-            if (!existing) {
-                level.set(segment.key, node);
-                if (parent) {
-                    parent.children.set(segment.key, node);
-                }
-            }
-            if (index === assignment.segments.length - 1) {
-                node.pages.push(toNavPage(page, assignment.displayTitle));
-                node.pageSortKeys.push(assignment.pageSortKey);
-            }
-            parent = node;
-            level = node.children;
+        if (dirParts.length > 1) {
+            return resolveL0Segments(normalized, "bmad-output");
         }
+        return ["other"];
     }
-    const topLevel = [...roots.values()].filter((node) => node.key !== "__root_pages__");
-    const rootPages = roots.get("__root_pages__")?.pages.sort(compareNavPages) ?? [];
-    const subgroups = sortMutableSubgroups(topLevel).map(finalizeSubgroup);
-    if (rootPages.length > 0) {
-        return [
-            ...subgroups,
-            {
-                key: "ungrouped",
-                label: "Ungrouped",
-                anchor: "ungrouped",
-                pageCount: rootPages.length,
-                collapsible: rootPages.length > 1,
-                open: false,
-                active: false,
-                pages: rootPages,
-                subgroups: [],
-                hasNestedSubgroups: false,
-            },
-        ];
-    }
-    return subgroups;
-}
-function createMutableSubgroup(key, label, sortOrder) {
-    return {
-        key,
-        label,
-        sortOrder,
-        pages: [],
-        pageSortKeys: [],
-        children: new Map(),
-    };
-}
-function finalizeSubgroup(node) {
-    const subgroups = sortMutableSubgroups([...node.children.values()]).map(finalizeSubgroup);
-    const pages = sortNavPages(node.pages);
-    const pageCount = pages.length + subgroups.reduce((sum, child) => sum + child.pageCount, 0);
-    return {
-        key: node.key,
-        label: node.label,
-        anchor: slugify(node.key),
-        pageCount,
-        collapsible: pageCount > 1 || subgroups.length > 0,
-        open: false,
-        active: false,
-        pages,
-        subgroups,
-        hasNestedSubgroups: subgroups.length > 0,
-    };
+    return null;
 }
-function flattenSingletonSubgroups(subgroups) {
-    const flattened = [];
-    for (const subgroup of subgroups) {
-        const nested = flattenSingletonSubgroups(subgroup.subgroups);
-        let current = {
-            ...subgroup,
-            subgroups: nested,
-            hasNestedSubgroups: nested.length > 0,
-        };
-        if (current.subgroups.length === 1 &&
-            current.pages.length === 0 &&
-            current.subgroups[0]) {
-            const child = current.subgroups[0];
-            current = {
-                ...child,
-                key: `${current.key}-${child.key}`,
-                label: `${current.label} › ${child.label}`,
-                anchor: slugify(`${current.key}-${child.key}`),
-            };
+function resolveL0Segments(normalized, categoryKey) {
+    const prefix = CATEGORY_PATH_PREFIXES[categoryKey];
+    if (categoryKey === "other") {
+        const parts = normalized.split("/");
+        if (parts.length <= 1) {
+            return [];
         }
-        if (current.pages.length === 0 && current.subgroups.length === 0) {
-            continue;
+        return parts.slice(0, Math.min(2, parts.length - 1));
+    }
+    if (prefix === undefined) {
+        return [];
+    }
+    if (prefix === "") {
+        const parts = normalized.split("/");
+        if (parts.length <= 1) {
+            return [];
         }
-        flattened.push(current);
+        return parts.slice(0, Math.min(2, parts.length - 1));
     }
-    return flattened;
+    if (!normalized.startsWith(prefix)) {
+        return [];
+    }
+    const relative = normalized.slice(prefix.length);
+    const dirParts = relative.split("/");
+    dirParts.pop();
+    if (dirParts.length === 0) {
+        return [];
+    }
+    return dirParts.slice(0, 2);
 }
-function promoteSingletonPages(subgroups) {
-    const promotedPages = [];
-    const kept = [];
-    for (const subgroup of subgroups) {
-        const nested = promoteSingletonPages(subgroup.subgroups);
-        const pages = sortNavPages([...subgroup.pages, ...nested.pages]);
-        const children = nested.subgroups;
-        const pageCount = pages.length + children.reduce((sum, child) => sum + child.pageCount, 0);
-        if (pages.length === 1 && children.length === 0) {
-            promotedPages.push(pages[0]);
-            continue;
+function insertIntoTree(root, segments, page) {
+    const capped = segments.slice(0, 2);
+    let current = root;
+    let path = [];
+    for (let i = 0; i < capped.length; i++) {
+        const segment = capped[i];
+        path = [...path, segment];
+        const key = path.join("/");
+        if (!current.has(segment)) {
+            current.set(segment, {
+                key,
+                label: humanizeFolderLabel(segment, path),
+                pages: [],
+                children: new Map(),
+                order: subgroupOrderCounter++,
+            });
         }
-        if (pages.length === 0 && children.length === 0) {
-            continue;
+        const node = current.get(segment);
+        if (i === capped.length - 1) {
+            node.pages.push(page);
         }
-        kept.push({
-            ...subgroup,
-            pages,
-            subgroups: children,
-            pageCount,
-            collapsible: pageCount > 1 || children.length > 0,
-            hasNestedSubgroups: children.length > 0,
-        });
-    }
-    return {
-        subgroups: kept,
-        pages: promotedPages,
-    };
-}
-function applyNavSubgroupState(subgroups, category, activePageSlug) {
-    return subgroups.map((subgroup) => {
-        const nested = applyNavSubgroupState(subgroup.subgroups, category, activePageSlug);
-        const containsActivePage = subgroup.pages.some((page) => page.slug === activePageSlug) ||
-            nested.some((child) => child.active || child.open);
-        return {
-            ...subgroup,
-            subgroups: nested,
-            hasNestedSubgroups: nested.length > 0,
-            active: containsActivePage,
-            open: containsActivePage,
-        };
-    });
-}
-function collectPages(subgroup) {
-    return [
-        ...subgroup.pages,
-        ...subgroup.subgroups.flatMap((child) => collectPages(child)),
-    ];
-}
-function sortMutableSubgroups(nodes) {
-    return [...nodes].sort((left, right) => {
-        if (left.sortOrder !== right.sortOrder) {
-            return left.sortOrder - right.sortOrder;
+        else {
+            current = node.children;
         }
-        return left.label.localeCompare(right.label);
-    });
-}
-function sortNavPages(pages) {
-    return [...pages].sort((left, right) => left.title.localeCompare(right.title));
-}
-function compareNavPages(left, right) {
-    return left.title.localeCompare(right.title);
-}
-function toNavPage(page, displayTitle) {
-    return {
-        title: displayTitle ?? page.title,
-        slug: page.slug,
-        href: `${page.slug}.html`,
-        sourcePath: page.sourcePath,
-    };
-}
-function extractSkillFolder(sourcePath) {
-    const normalized = sourcePath.replace(/\\/g, "/");
-    const match = normalized.match(/^\.agents\/skills\/([^/]+)\/SKILL\.md$/);
-    return match?.[1] ?? null;
+    }
 }
-function labelForPathSegment(segment) {
+function humanizeFolderLabel(segment, path) {
+    if (segment.startsWith("epic-")) {
+        const num = segment.slice("epic-".length);
+        return `Epic ${num}`;
+    }
     if (FOLDER_LABELS[segment]) {
         return FOLDER_LABELS[segment];
     }
+    if (path[0] === "planning" && path.length === 2) {
+        return (FOLDER_LABELS[segment] ??
+            segment
+                .split("-")
+                .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                .join(" "));
+    }
     return segment
         .split("-")
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
-function formatAgentTitle(agent) {
-    const icon = agent.icon.trim();
-    if (icon.length > 0) {
-        return `${icon} ${agent.name} — ${agent.title}`;
+function sortImplementationStoryPages(root) {
+    const implNode = root.get("implementation-stories");
+    if (!implNode) {
+        return;
     }
-    return `${agent.name} — ${agent.title}`;
-}
-function slugify(value) {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-}
-async function parseBmadHelpCsv(csvContent, projectRoot) {
-    const skills = new Map();
-    const lines = csvContent.split(/\r?\n/).filter(Boolean);
-    if (lines.length <= 1) {
-        return { skills, agents: new Map() };
-    }
-    for (const line of lines.slice(1)) {
-        const row = parseCsvLine(line);
-        if (row.length < 8) {
-            continue;
+    const epicEntries = [...implNode.children.entries()].sort(([, a], [, b]) => {
+        const epicA = parseInt(a.key.match(/epic-(\d+)/)?.[1] ?? "0", 10);
+        const epicB = parseInt(b.key.match(/epic-(\d+)/)?.[1] ?? "0", 10);
+        if (epicA !== epicB) {
+            return epicA - epicB;
         }
-        const module = row[0]?.trim() ?? "";
-        const skill = row[1]?.trim() ?? "";
-        const displayName = row[2]?.trim() ?? "";
-        const description = row[4]?.trim() ?? "";
-        const phase = row[7]?.trim() ?? "";
-        if (!skill || skill === "_meta" || !displayName) {
-            continue;
+        return a.order - b.order;
+    });
+    implNode.children = new Map(epicEntries);
+    for (const [, epicNode] of epicEntries) {
+        epicNode.pages.sort((a, b) => {
+            const numsA = storyNumbers(a.sourcePath);
+            const numsB = storyNumbers(b.sourcePath);
+            if (numsA.epic !== numsB.epic) {
+                return numsA.epic - numsB.epic;
+            }
+            return numsA.story - numsB.story;
+        });
+    }
+}
+function finalizeSubgroups(nodes, options) {
+    const result = [];
+    const rootPromoted = [];
+    const sortedNodes = [...nodes.values()].sort((a, b) => a.order - b.order);
+    for (const node of sortedNodes) {
+        const finalized = finalizeNode(node, options);
+        rootPromoted.push(...finalized.promoted);
+        if (finalized.subgroup) {
+            result.push(finalized.subgroup);
         }
-        if (!skills.has(skill)) {
-            skills.set(skill, {
-                skill,
-                displayName,
-                phase,
-                module,
-                deprecated: /deprecated/i.test(description),
-            });
+    }
+    return { subgroups: result, rootPromoted };
+}
+function finalizeNode(node, options) {
+    const promoted = [...node.pages];
+    const childSubgroups = [];
+    const sortedChildren = [...node.children.values()].sort((a, b) => a.order - b.order);
+    for (const child of sortedChildren) {
+        const finalizedChild = finalizeNode(child, options);
+        promoted.push(...finalizedChild.promoted);
+        if (finalizedChild.subgroup) {
+            childSubgroups.push(finalizedChild.subgroup);
         }
     }
-    const agents = await loadAgentEntries(projectRoot, skills);
-    return { skills, agents };
+    const totalPageCount = promoted.length + childSubgroups.reduce((sum, sg) => sum + sg.pageCount, 0);
+    if (totalPageCount === 0) {
+        return { promoted: [] };
+    }
+    if (totalPageCount === 1 && promoted.length === 1) {
+        return { promoted };
+    }
+    const containsActive = nodeOrChildrenContainActive(promoted, childSubgroups, options);
+    const collapsible = totalPageCount > 1;
+    const subgroup = {
+        key: node.key,
+        label: node.label,
+        pageCount: totalPageCount,
+        collapsible,
+        open: containsActive,
+        pages: promoted,
+    };
+    if (childSubgroups.length > 0) {
+        subgroup.subgroups = childSubgroups;
+        applyIndexOpenState(subgroup, options);
+    }
+    if (options.indexBuild && collapsible && !containsActive) {
+        subgroup.open = false;
+    }
+    return { promoted: [], subgroup };
 }
-async function loadAgentEntries(projectRoot, skills) {
-    const agents = new Map();
-    for (const skillFolder of skills.keys()) {
-        if (!skillFolder.startsWith("bmad-agent-")) {
-            continue;
+function applyIndexOpenState(subgroup, options) {
+    if (!options.indexBuild) {
+        return;
+    }
+    for (const child of subgroup.subgroups ?? []) {
+        const childActive = subgroupContainsActiveInChild(child, options);
+        if (child.collapsible && !childActive) {
+            child.open = false;
         }
-        const customizePath = path.join(projectRoot, ".agents/skills", skillFolder, "customize.toml");
-        try {
-            const toml = await fs.readFile(customizePath, "utf-8");
-            const agent = parseAgentCustomize(toml, skillFolder);
-            if (agent) {
-                agents.set(skillFolder, agent);
-            }
+        applyIndexOpenState(child, options);
+    }
+}
+function nodeOrChildrenContainActive(pages, childSubgroups, options) {
+    if (!options.activePageSlug && !options.activeSourcePath) {
+        return false;
+    }
+    for (const page of pages) {
+        if (page.slug === options.activePageSlug ||
+            page.sourcePath === options.activeSourcePath) {
+            return true;
         }
-        catch {
-            continue;
+    }
+    for (const child of childSubgroups) {
+        if (subgroupContainsActiveInChild(child, options)) {
+            return true;
         }
     }
-    return agents;
+    return false;
 }
-function parseAgentCustomize(toml, skillFolder) {
-    if (!/^\[agent\]/m.test(toml)) {
-        return null;
+function subgroupContainsActiveInChild(subgroup, options) {
+    if (!options.activePageSlug && !options.activeSourcePath) {
+        return false;
     }
-    const agentBlock = extractTomlSection(toml, "agent");
-    const name = readTomlString(agentBlock, "name") ?? skillFolder;
-    const title = readTomlString(agentBlock, "title") ?? name;
-    const icon = readTomlString(agentBlock, "icon") ?? "";
-    return { skill: skillFolder, name, title, icon };
-}
-function extractTomlSection(content, section) {
-    const pattern = new RegExp(`^\\[${section}\\][\\s\\S]*?(?=^\\[[^\\]]+\\]|$)`, "m");
-    const match = content.match(pattern);
-    return match?.[0] ?? "";
-}
-function readTomlString(section, key) {
-    const pattern = new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m");
-    const match = section.match(pattern);
-    return match?.[1];
+    for (const page of subgroup.pages) {
+        if (page.slug === options.activePageSlug ||
+            page.sourcePath === options.activeSourcePath) {
+            return true;
+        }
+    }
+    for (const child of subgroup.subgroups ?? []) {
+        if (subgroupContainsActiveInChild(child, options)) {
+            return true;
+        }
+    }
+    return false;
 }
-function parseCsvLine(line) {
-    const values = [];
-    let current = "";
-    let inQuotes = false;
-    for (let index = 0; index < line.length; index += 1) {
-        const char = line[index];
-        if (char === '"') {
-            if (inQuotes && line[index + 1] === '"') {
-                current += '"';
-                index += 1;
+/**
+ * Walk finalized category subgroups and return the ordered ancestor trail
+ * (outer → inner) for the active page. Does not include the page itself.
+ */
+export function resolveActiveSubgroupTrail(subgroups, options) {
+    const trail = [];
+    function walk(nodes) {
+        for (const node of nodes) {
+            if (!subgroupContainsActiveInChild(node, options)) {
+                continue;
             }
-            else {
-                inQuotes = !inQuotes;
+            trail.push({ key: node.key, label: node.label });
+            if (node.subgroups?.length) {
+                walk(node.subgroups);
             }
-            continue;
+            return true;
         }
-        if (char === "," && !inQuotes) {
-            values.push(current);
-            current = "";
-            continue;
-        }
-        current += char;
+        return false;
     }
-    values.push(current);
-    return values;
+    walk(subgroups);
+    return trail;
+}
+/** Exported for unit tests — maps category keys to path strip prefixes. */
+export function categoryPathPrefix(categoryKey) {
+    return CATEGORY_PATH_PREFIXES[categoryKey];
+}
+/** Exported for unit tests — humanizes a folder segment. */
+export function humanizeSegment(segment) {
+    return humanizeFolderLabel(segment, [segment]);
 }
 //# sourceMappingURL=nav-grouping.js.map