viteboard 0.1.0 → 0.1.1

package/src/shell/Sidebar.ts

@@ -41,9 +41,22 @@ export type SidebarCallbacks = {
 
 type SidebarDragItem =
   | { kind: "doc"; rootId: string; path: string }
+  | { kind: "capability"; rootId: string; path: string }
   | { kind: "board"; rootId: string; boardId: string }
   | { kind: "dir"; rootId: string; path: string };
 
+type CanonicalNode = {
+  id: string;
+  kind: "folder" | "docsRoot" | "doc" | "board" | "capability" | "file";
+  name: string;
+  projectPath: string;
+  root?: DocsRootSummary;
+  contentPath?: string;
+  /** Docs mode promotes a docs root's children into this physical parent. */
+  docsContainerRoot?: DocsRootSummary;
+  children: CanonicalNode[];
+};
+
 // ---------------------------------------------------------------------------
 // Path-segment tree used to group docs roots into a nested hierarchy.
 // ---------------------------------------------------------------------------
@@ -120,13 +133,15 @@ export class Sidebar {
   private callbacks: SidebarCallbacks;
   private contextMenu?: HTMLElement;
   private draggedItem?: SidebarDragItem;
+  private dropExpandTimer?: number;
+  private dropExpandTarget?: HTMLElement;
 
   /** Last full workspace state — kept so we can re-render on mode toggle. */
   private lastWorkspace: WorkspaceState = { projects: [] };
   private lastTreesByRoot = new Map<string, TreeNode[]>();
   private lastTreesByProject = new Map<string, TreeNode[]>();
-  /** Track which projects have "browse mode" enabled (shows full filesystem) */
-  private browseModeProjects = new Set<string>();
+  /** Raw mode adds muted project files and folders to the docs-focused tree. */
+  private rawModeProjects = new Set<string>();
 
   constructor(parent: HTMLElement, callbacks: SidebarCallbacks) {
     this.callbacks = callbacks;
@@ -214,22 +229,6 @@ export class Sidebar {
 
 
 
-  /** Exit browse mode for all projects (called after content refresh). */
-  clearBrowseMode(): void {
-    if (this.browseModeProjects.size === 0) return;
-    this.browseModeProjects.clear();
-    this.render();
-  }
-
-  private toggleBrowseMode(projectId: string): void {
-    if (this.browseModeProjects.has(projectId)) {
-      this.browseModeProjects.delete(projectId);
-    } else {
-      this.browseModeProjects.add(projectId);
-    }
-    this.render();
-  }
-
   setActive(hash: string): void {
     // 1. Clear previous active state.
     for (const a of new Set(this.links.values())) a.classList.remove("active");
@@ -254,6 +253,12 @@ export class Sidebar {
     this.syncCollapsed(hash);
   }
 
+  private toggleRawMode(projectId: string): void {
+    if (this.rawModeProjects.has(projectId)) this.rawModeProjects.delete(projectId);
+    else this.rawModeProjects.add(projectId);
+    this.render();
+  }
+
   /**
    * Open every collapsible that is an ancestor of the active page, while
    * preserving the user's existing open/close state elsewhere.
@@ -303,18 +308,21 @@ export class Sidebar {
 
     // Project header.
     open.add(projectId);
+    // The docs-root folder is a real, collapsible tree row.
+    open.add(rootId);
 
-    // Path-segment keys: auto-open the filesystem scaffolding leading to /docs/
+    // Open real project-folder ancestors leading to the docs root. The docs
+    // root itself is represented by its parent's tagged row in Docs mode.
     const displayParts = displayPath.split("/").filter(Boolean).slice(0, -1);
     let acc = "";
     for (const part of displayParts) {
       acc = acc ? `${acc}/${part}` : part;
-      const candidate = `pathseg:${projectId}:${acc}`;
-      if (this.collapsibles.has(candidate)) open.add(candidate);
+      const folderKey = `folder:${projectId}:${acc}`;
+      if (this.collapsibles.has(folderKey)) open.add(folderKey);
     }
 
     // Doc directory keys: every parent dir of the current file path.
-    if (section === "docs" && rest) {
+    if ((section === "docs" || section === "capabilities") && rest) {
       const parts = rest.split("/");
       for (let i = 1; i < parts.length; i++) {
         const dirPath = parts.slice(0, i).join("/");
@@ -333,7 +341,7 @@ export class Sidebar {
     treesByRoot: Map<string, TreeNode[]>
   ): HTMLElement {
     const { id: projectId, label, docsRoots: roots } = project;
-    const isRaw = this.browseModeProjects.has(projectId);
+    const isRaw = this.rawModeProjects.has(projectId);
 
     const body = document.createElement("div");
     body.className = "nav-repo-body";
@@ -351,8 +359,13 @@ export class Sidebar {
     const text = document.createElement("span");
     text.className = "nav-repo-label-text";
     text.textContent = label;
+    const projectDocsRoot = !isRaw && roots.find((root) => normalizeDirPath(root.displayPath) === "docs");
+    const docsBadge = document.createElement("span");
+    docsBadge.className = "nav-tree-badge";
+    docsBadge.textContent = "DOCS";
+    docsBadge.hidden = !projectDocsRoot;
 
-    // Three-dot menu button (replaces wiki link + toggle)
+    // Project-level actions never alter the navigation model.
     const moreBtn = document.createElement("button");
     moreBtn.className = "nav-repo-more";
     moreBtn.type = "button";
@@ -366,7 +379,7 @@ export class Sidebar {
           icon: isRaw ? DOC_ICON_HTML : DIRECTORY_ICON_HTML,
           iconClass: isRaw ? "nav-ctx-doc" : "nav-ctx-dir",
           label: isRaw ? "View: Docs" : "View: Raw",
-          action: () => this.toggleBrowseMode(projectId),
+          action: () => this.toggleRawMode(projectId),
         },
         {
           icon: EDIT_ICON_HTML, iconClass: "nav-ctx-edit", label: "Wiki",
@@ -394,7 +407,7 @@ export class Sidebar {
       ]);
     });
 
-    header.append(chevron, text, moreBtn);
+    header.append(chevron, text, docsBadge, moreBtn);
 
     this.registerCollapsible(projectId, body, group, header as HTMLButtonElement, true);
     header.addEventListener("click", () => this.toggleCollapsible(projectId));
@@ -406,67 +419,137 @@ export class Sidebar {
       moreBtn.click();
     });
 
-    const projectDropRoot = roots[0];
-    if (projectDropRoot) this.enableDirectoryDropTarget(header, projectDropRoot.id, "");
+    const tree = buildCanonicalTree(project, this.lastTreesByProject.get(projectId) ?? [], treesByRoot);
+    const visibleTree = isRaw
+      ? tree
+      : collapseDocsRootRows(visibleCanonicalNodes(tree, false));
+    if (visibleTree.length === 0) {
+      const note = document.createElement("div");
+      note.className = "nav-label nav-empty-copy";
+      note.textContent = "No folders found.";
+      body.appendChild(note);
+    } else {
+      body.appendChild(this.renderCanonicalNodes(project, visibleTree, 0, isRaw));
+    }
 
-    // ── Render tree: one unified view, same structure in both modes ──
-    if (isRaw) {
-      // Raw mode: full project filesystem. /docs/ folders render full content.
-      // Non-docs dirs are subtly muted. Right-click non-docs → create /docs/.
-      const projectTree = this.lastTreesByProject.get(projectId) ?? [];
-      for (const node of projectTree) {
-        if (node.type === "dir") {
-          body.appendChild(this.renderBrowseNode(project, node, treesByRoot));
-        }
+    group.append(header, body);
+    return group;
+  }
+
+  /** Render the one project-relative tree used by the sidebar. */
+  private renderCanonicalNodes(project: WorkspaceProject, nodes: CanonicalNode[], depth: number, isRaw: boolean): HTMLElement {
+    const fragment = document.createElement("div");
+    for (const node of sortCanonicalNodes(nodes)) {
+      if (node.kind === "doc" || node.kind === "board" || node.kind === "capability" || node.kind === "file") {
+        fragment.appendChild(this.renderCanonicalFile(node, depth));
+        continue;
       }
-    } else {
-      // Docs mode: only /docs/ roots and their content.
-      if (roots.length === 0) {
-        const note = document.createElement("div");
-        note.className = "nav-label nav-empty-copy";
-        note.textContent = "No docs folders found.";
-        body.appendChild(note);
+
+      const group = document.createElement("div");
+      group.className = "nav-tree-group";
+      group.style.setProperty("--tree-depth", String(depth));
+      const body = document.createElement("div");
+      body.className = "nav-tree-children";
+      const toggle = document.createElement("button");
+      toggle.className = "nav-tree-row nav-tree-folder" +
+        (node.kind === "docsRoot" ? " nav-tree-docs-root" : "") +
+        (node.docsContainerRoot ? " nav-tree-docs-container" : "") +
+        (!node.root ? " nav-tree-scaffold" : "");
+      toggle.type = "button";
+      toggle.style.setProperty("--tree-depth", String(depth));
+      const chevron = document.createElement("span");
+      chevron.className = "nav-repo-chevron";
+      chevron.textContent = "›";
+      const label = document.createElement("span");
+      label.textContent = node.name;
+      toggle.append(chevron, label);
+      if (node.kind === "docsRoot" || node.docsContainerRoot) {
+        const badge = document.createElement("span");
+        badge.className = "nav-tree-badge";
+        badge.textContent = "DOCS";
+        toggle.appendChild(badge);
+      }
+
+      const key = node.kind === "docsRoot" || node.docsContainerRoot
+        ? (node.docsContainerRoot ?? node.root)!.id
+        : node.root
+        ? `doc:${node.root.id}:${node.contentPath ?? ""}`
+        : `folder:${project.id}:${node.projectPath}`;
+      this.registerCollapsible(key, body, group, toggle, true);
+      toggle.addEventListener("click", () => this.toggleCollapsible(key));
+
+      if (node.kind === "docsRoot" || node.docsContainerRoot) {
+        const root = node.docsContainerRoot ?? node.root!;
+        toggle.addEventListener("contextmenu", (e) => {
+          e.preventDefault();
+          this.openDirContextMenu(e.clientX, e.clientY, root, "");
+        });
+        this.enableDirectoryDropTarget(group, root.id, "");
+      } else if (node.root) {
+        const root = node.root;
+        const contentPath = node.contentPath ?? "";
+        this.enableDragSource(toggle, { kind: "dir", rootId: root.id, path: contentPath });
+        this.enableDirectoryDropTarget(group, root.id, contentPath);
+        group.addEventListener("contextmenu", (e) => {
+          e.preventDefault();
+          this.openDirContextMenu(e.clientX, e.clientY, root, contentPath);
+        });
       } else {
-        const pathTree = buildPathTree(roots);
-        body.appendChild(this.renderPathNodes(pathTree, treesByRoot, projectId));
+        toggle.addEventListener("contextmenu", (e) => {
+          e.preventDefault();
+          this.showContextMenu(e.clientX, e.clientY, node.name, [{
+            icon: DIRECTORY_ICON_HTML,
+            iconClass: "nav-ctx-dir",
+            label: "Create docs folder here",
+            action: () => this.callbacks.onCreateDocsFolder(project.id, node.projectPath),
+          }]);
+        });
       }
-    }
 
-    // ── Footer links (always visible when docs exist) ──
-    if (roots.length > 0) {
-      const boardsRow = document.createElement("div");
-      boardsRow.className = "nav-project-boards-row";
-      const allBoardsLink = this.link(
-        projectBoardsHref(projectId),
-        "All Boards",
-        `boards:${projectId}`
-      );
-      allBoardsLink.classList.add("nav-link-board");
-      allBoardsLink.insertAdjacentHTML("afterbegin", BOARD_ICON_HTML);
-      boardsRow.appendChild(allBoardsLink);
-      body.appendChild(boardsRow);
-
-      const firstRootWithCaps = roots.find((r) => {
-        const tree = treesByRoot.get(r.id) ?? [];
-        const capsDir = tree.find((n) => n.type === "dir" && n.name === "capabilities");
-        return capsDir?.type === "dir" &&
-          capsDir.children.some((n) => n.type === "file" && n.name.endsWith(".md"));
-      }) ?? roots[0];
-      const capsRow = document.createElement("div");
-      capsRow.className = "nav-project-boards-row";
-      const allCapsLink = this.link(
-        rootCapabilitiesHref(firstRootWithCaps.id),
-        "All Capabilities",
-        `caps:${projectId}`
-      );
-      allCapsLink.classList.add("nav-link-capability");
-      allCapsLink.insertAdjacentHTML("afterbegin", CAPABILITY_ICON_HTML);
-      capsRow.appendChild(allCapsLink);
-      body.appendChild(capsRow);
+      body.appendChild(this.renderCanonicalNodes(project, node.children, depth + 1, isRaw));
+      group.append(toggle, body);
+      fragment.appendChild(group);
     }
+    return fragment;
+  }
 
-    group.append(header, body);
-    return group;
+  private renderCanonicalFile(node: CanonicalNode, depth: number): HTMLElement {
+    if (node.kind === "file") {
+      const file = document.createElement("div");
+      file.className = "nav-tree-row nav-tree-file";
+      file.style.setProperty("--tree-depth", String(depth));
+      file.textContent = node.name;
+      return file;
+    }
+    const root = node.root!;
+    const path = node.contentPath!;
+    const href = node.kind === "doc"
+      ? rootDocHref(root.id, path)
+      : node.kind === "board"
+      ? rootBoardHref(root.id, boardIdFromFilePath(path))
+      : rootCapabilityHref(root.id, path);
+    const label = node.kind === "doc" && node.name === "index.md"
+      ? "Overview"
+      : prettify(node.kind === "board" ? boardIdFromFilePath(node.name) : node.name);
+    const link = this.link(href, label, `${node.kind}:${root.id}:${path}`);
+    link.classList.add("nav-tree-row", `nav-tree-${node.kind}`);
+    link.style.setProperty("--tree-depth", String(depth));
+    link.insertAdjacentHTML("afterbegin", node.kind === "board"
+      ? BOARD_ICON_HTML
+      : node.kind === "capability"
+      ? CAPABILITY_ICON_HTML
+      : DOC_ICON_HTML);
+    this.enableDragSource(link, node.kind === "board"
+      ? { kind: "board", rootId: root.id, boardId: boardIdFromFilePath(path) }
+      : node.kind === "capability"
+      ? { kind: "capability", rootId: root.id, path }
+      : { kind: "doc", rootId: root.id, path });
+    link.addEventListener("contextmenu", (e) => {
+      e.preventDefault();
+      if (node.kind === "board") this.openBoardContextMenu(e.clientX, e.clientY, root, boardIdFromFilePath(path));
+      else if (node.kind === "doc") this.openDocContextMenu(e.clientX, e.clientY, root, path);
+    });
+    return link;
   }
 
   // ---------- Browse mode (filesystem view) ----------
@@ -828,21 +911,45 @@ export class Sidebar {
       e.stopPropagation();
       if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
       el.classList.add("nav-drop-target");
+      this.scheduleDropExpand(el);
     });
     el.addEventListener("dragleave", (e) => {
       if (el.contains(e.relatedTarget as Node | null)) return;
       el.classList.remove("nav-drop-target");
+      this.clearDropExpand(el);
     });
     el.addEventListener("drop", (e) => {
       const item = this.currentDragItem(e);
       if (!item || !this.canDropItem(item, rootId, targetDir)) return;
       e.preventDefault();
       e.stopPropagation();
+      this.clearDropExpand(el);
       this.clearDropTargets();
       this.moveDraggedItem(item, targetDir);
     });
   }
 
+  /** Match IDE tree behavior: pause over a valid collapsed folder to open it. */
+  private scheduleDropExpand(el: HTMLElement): void {
+    if (this.dropExpandTarget === el || !el.dataset.collapsibleKey) return;
+    this.clearDropExpand();
+    this.dropExpandTarget = el;
+    this.dropExpandTimer = window.setTimeout(() => {
+      const key = el.dataset.collapsibleKey;
+      if (key) this.applyCollapsed(key, false);
+      el.classList.add("nav-drop-auto-expanded");
+      this.dropExpandTimer = undefined;
+    }, 650);
+  }
+
+  private clearDropExpand(target?: HTMLElement): void {
+    if (target && this.dropExpandTarget !== target) return;
+    if (this.dropExpandTimer !== undefined) window.clearTimeout(this.dropExpandTimer);
+    this.dropExpandTimer = undefined;
+    this.dropExpandTarget?.classList.remove("nav-drop-auto-expanded");
+    this.dropExpandTarget = undefined;
+  }
+
   private currentDragItem(e: DragEvent): SidebarDragItem | undefined {
     if (this.draggedItem) return this.draggedItem;
     const raw = e.dataTransfer?.getData("application/x-docs-nav-item");
@@ -851,7 +958,7 @@ export class Sidebar {
       const parsed = JSON.parse(raw) as SidebarDragItem;
       if (
         parsed &&
-        (parsed.kind === "doc" || parsed.kind === "board" || parsed.kind === "dir") &&
+        (parsed.kind === "doc" || parsed.kind === "capability" || parsed.kind === "board" || parsed.kind === "dir") &&
         typeof parsed.rootId === "string"
       ) {
         return parsed;
@@ -866,6 +973,10 @@ export class Sidebar {
     if (item.rootId !== rootId) return false;
     const normalizedTarget = normalizeDirPath(targetDir);
     if (item.kind === "doc") return parentDir(item.path) !== normalizedTarget;
+    if (item.kind === "capability") {
+      return normalizedTarget === "capabilities" ||
+        (normalizedTarget.startsWith("capabilities/") && parentDir(item.path) !== normalizedTarget);
+    }
     if (item.kind === "board") return parentDir(item.boardId) !== normalizedTarget;
 
     const source = normalizeDirPath(item.path);
@@ -877,7 +988,7 @@ export class Sidebar {
 
   private moveDraggedItem(item: SidebarDragItem, targetDir: string): void {
     const normalizedTarget = normalizeDirPath(targetDir);
-    if (item.kind === "doc") {
+    if (item.kind === "doc" || item.kind === "capability") {
       this.callbacks.onMoveDoc(item.rootId, item.path, normalizedTarget);
     } else if (item.kind === "board") {
       this.callbacks.onMoveBoard(item.rootId, item.boardId, normalizedTarget);
@@ -887,6 +998,7 @@ export class Sidebar {
   }
 
   private clearDropTargets(): void {
+    this.clearDropExpand();
     this.element.querySelectorAll(".nav-drop-target").forEach((node) => {
       node.classList.remove("nav-drop-target");
     });
@@ -984,6 +1096,7 @@ export class Sidebar {
     defaultCollapsed: boolean
   ): void {
     this.collapsibles.set(key, { body, group, btn });
+    group.dataset.collapsibleKey = key;
     this.applyCollapsed(key, this.collapsedState.get(key) ?? defaultCollapsed);
   }
 
@@ -1310,6 +1423,192 @@ function rootCapabilitiesHref(rootId: string): string {
   return `#/root/${encodeURIComponent(rootId)}/capabilities`;
 }
 
+function rootCapabilityHref(rootId: string, path: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/capabilities/${encodeURIComponent(path)}`;
+}
+
+/**
+ * Merge the project directory tree and each mounted docs-root tree by their
+ * project-relative path. A physical folder is represented exactly once.
+ */
+function buildCanonicalTree(
+  project: WorkspaceProject,
+  projectTree: TreeNode[],
+  treesByRoot: Map<string, TreeNode[]>
+): CanonicalNode[] {
+  const byPath = new Map<string, CanonicalNode>();
+  const roots: CanonicalNode[] = [];
+
+  const ensureFolder = (projectPath: string): CanonicalNode => {
+    const normalized = normalizeDirPath(projectPath);
+    const existing = byPath.get(normalized);
+    if (existing) return existing;
+    const parentPath = parentDir(normalized);
+    const node: CanonicalNode = {
+      id: `folder:${project.id}:${normalized}`,
+      kind: "folder",
+      name: normalized.split("/").pop() ?? project.label,
+      projectPath: normalized,
+      children: [],
+    };
+    byPath.set(normalized, node);
+    // The project itself is the implicit root. Never create a blank tree row
+    // just to parent top-level folders.
+    if (normalized && parentPath) ensureFolder(parentPath).children.push(node);
+    else roots.push(node);
+    return node;
+  };
+
+  const addProjectFolders = (nodes: TreeNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "dir") {
+        ensureFolder(node.path);
+        addProjectFolders(node.children);
+      } else {
+        const file: CanonicalNode = {
+          id: `file:${project.id}:${node.path}`,
+          kind: "file",
+          name: node.name,
+          projectPath: node.path,
+          children: [],
+        };
+        byPath.set(node.path, file);
+        const parentPath = parentDir(node.path);
+        if (parentPath) ensureFolder(parentPath).children.push(file);
+        else roots.push(file);
+      }
+    }
+  };
+  addProjectFolders(projectTree);
+
+  for (const root of project.docsRoots) {
+    const rootPath = normalizeDirPath(root.displayPath);
+    const rootNode = ensureFolder(rootPath);
+    rootNode.kind = "docsRoot";
+    rootNode.id = `root:${root.id}`;
+    rootNode.root = root;
+    rootNode.contentPath = "";
+
+    const addDocsNodes = (nodes: TreeNode[]) => {
+      for (const node of nodes) {
+        const projectPath = [rootPath, node.path].filter(Boolean).join("/");
+        if (node.type === "dir") {
+          const folder = ensureFolder(projectPath);
+          // A nested docs root is assigned when its own root is processed.
+          if (folder.kind !== "docsRoot") {
+            folder.root = root;
+            folder.contentPath = node.path;
+          }
+          addDocsNodes(node.children);
+          continue;
+        }
+        if (!node.name.endsWith(".md") && !node.name.endsWith(".board.json")) continue;
+        const parentPath = parentDir(projectPath);
+        const isBoard = node.name.endsWith(".board.json");
+        const isCapability = node.path.startsWith("capabilities/");
+        const existing = byPath.get(projectPath);
+        const content = existing ?? {
+          id: "",
+          kind: "file" as const,
+          name: node.name,
+          projectPath,
+          children: [],
+        };
+        content.id = `${isBoard ? "board" : isCapability ? "capability" : "doc"}:${root.id}:${node.path}`;
+        content.kind = isBoard ? "board" : isCapability ? "capability" : "doc";
+        content.root = root;
+        content.contentPath = node.path;
+        if (!existing) {
+          byPath.set(projectPath, content);
+          if (parentPath) ensureFolder(parentPath).children.push(content);
+          else roots.push(content);
+        }
+      }
+    };
+    addDocsNodes(treesByRoot.get(root.id) ?? []);
+  }
+
+  const assignRoot = (node: CanonicalNode, inherited?: DocsRootSummary): void => {
+    const owner = node.kind === "docsRoot" ? node.root : node.root ?? inherited;
+    if (node.kind === "folder" && owner) {
+      node.root = owner;
+      const rootPath = normalizeDirPath(owner.displayPath);
+      node.contentPath = node.projectPath.slice(rootPath.length).replace(/^\//, "");
+    }
+    for (const child of node.children) assignRoot(child, owner);
+  };
+  for (const node of roots) assignRoot(node);
+  return roots;
+}
+
+function sortCanonicalNodes(nodes: CanonicalNode[]): CanonicalNode[] {
+  return [...nodes].sort((a, b) => {
+    const rank = (node: CanonicalNode) => {
+      if (node.kind === "doc" && node.name === "index.md") return 0;
+      // Content is the primary navigation surface. Folders follow it as
+      // structural organization, matching the focused docs workflow.
+      if (node.kind === "doc") return 1;
+      if (node.kind === "capability") return 2;
+      if (node.kind === "board") return 3;
+      if (node.kind === "folder" || node.kind === "docsRoot") return 4;
+      return 5;
+    };
+    return rank(a) - rank(b) || a.name.localeCompare(b.name, undefined, { sensitivity: "accent" });
+  });
+}
+
+/** Docs mode keeps docs roots and their physical ancestor paths only. */
+function visibleCanonicalNodes(nodes: CanonicalNode[], isRaw: boolean, insideDocsRoot = false): CanonicalNode[] {
+  if (isRaw) return nodes;
+  const visible: CanonicalNode[] = [];
+  for (const node of nodes) {
+    if (node.kind === "docsRoot") {
+      visible.push({ ...node, children: visibleCanonicalNodes(node.children, false, true) });
+      continue;
+    }
+    if (insideDocsRoot) {
+      if (node.kind === "file") continue;
+      if (node.kind === "folder") {
+        const children = visibleCanonicalNodes(node.children, false, true);
+        if (node.name !== "assets" || children.length > 0) visible.push({ ...node, children });
+      } else {
+        visible.push(node);
+      }
+      continue;
+    }
+    if (node.kind === "folder") {
+      const children = visibleCanonicalNodes(node.children, false);
+      if (children.length > 0) visible.push({ ...node, children });
+    }
+  }
+  return visible;
+}
+
+/**
+ * Docs mode keeps the physical path to a docs root but removes the redundant
+ * docs row itself. Its parent owns the DOCS badge and root-level actions.
+ */
+function collapseDocsRootRows(nodes: CanonicalNode[]): CanonicalNode[] {
+  const out: CanonicalNode[] = [];
+  for (const node of nodes) {
+    if (node.kind === "docsRoot") {
+      out.push(...collapseDocsRootRows(node.children));
+      continue;
+    }
+    if (node.kind !== "folder") {
+      out.push(node);
+      continue;
+    }
+    const directRoot = node.children.find((child) => child.kind === "docsRoot")?.root;
+    out.push({
+      ...node,
+      docsContainerRoot: directRoot,
+      children: collapseDocsRootRows(node.children),
+    });
+  }
+  return out;
+}
+
 function prettify(name: string): string {
   const base = name.replace(/\.md$/, "").replace(/[-_]/g, " ");
   return base.charAt(0).toUpperCase() + base.slice(1);
@@ -1336,7 +1635,7 @@ function parentDir(path: string): string {
 }
 
 function dragItemLabel(item: SidebarDragItem): string {
-  if (item.kind === "doc") return item.path;
+  if (item.kind === "doc" || item.kind === "capability") return item.path;
   if (item.kind === "board") return item.boardId;
   return item.path;
 }