chore: clean up content phase organization

apps/cli/sync.ts

@@ -17,11 +17,14 @@
  * file sits under in `work/1/<Difficulty>/<Category>/`. A problem outside the
  * plan (warm-ups) has no topic, so it groups under its category instead.
  *
- * Topic folders are real route segments (`/tree-dfs/invert-binary-tree`), not
- * `(group)` folders, so a hand-written `index.mdx` in one is the topic's
- * landing page at `/tree-dfs` and Blume links the sidebar group row to it.
- * Sync never writes or moves an `index.mdx`, and never removes a folder that
- * still holds one.
+ * Topics nest under their README PHASE: `(01-linear-structures)/tree-dfs/`.
+ * The phase folder is a Blume `(group)` — a sidebar section with its own
+ * script-owned `meta.ts`, adding no route segment — while the topic folder is
+ * a real segment (`/tree-dfs/invert-binary-tree`), so a hand-written
+ * `index.mdx` in it is the topic's landing page at `/tree-dfs` and Blume links
+ * the sidebar group row to it. Sync never writes or moves an `index.mdx`, and
+ * never removes a folder that still holds one. An unplanned category group has
+ * no phase and sits at the content root.
  *
  * Only the first-solve bucket is read: work/3 and work/7 hold blind re-solves
  * of problems whose page already exists (see work.ts), and a fresh scaffold
@@ -171,12 +174,29 @@ function parseHeader(header: string): Header {
 
 // ── README topic map ─────────────────────────────────────────────
 
+/** A campaign phase: `## Phase N — Name · Weeks …` in the README. */
+interface Phase {
+  order: number;
+  name: string;
+}
+
 /** A campaign topic: `<strong>NN. Name</strong>` in the README table. */
 interface Topic {
   order?: number; // README topic number; absent for an unplanned problem's category group
   name: string;
+  phase?: Phase; // absent for an unplanned category group
 }
 
+/** README phase names → the short labels the overview page uses. */
+const PHASE_ALIASES: Record<string, string> = {
+  "Nodal & Grid Structures": "Nodal & Grid",
+  "Hierarchical Structures": "Hierarchical",
+  "Relational Structures": "Relational",
+  "Decision-Space Exploration": "Decision Space",
+};
+
+const ROMAN = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"];
+
 const TOPIC_ALIASES: Record<string, string> = {
   "Hash-Based Lookup": "Hash Table",
 };
@@ -224,10 +244,16 @@ const TOPIC_ICONS: Record<string, string> = {
 async function readmeTopics(): Promise<Map<number, Topic>> {
   const md = await Bun.file(join(ROOT, "README.md")).text();
   const map = new Map<number, Topic>();
+  let phase: Phase | undefined;
   let topic: Topic | null = null;
   for (const line of md.split("\n")) {
+    const p = line.match(/^## Phase ([IVX]+) — (.+?) · /);
+    if (p) {
+      const name = p[2]!.replaceAll("&amp;", "&");
+      phase = { order: ROMAN.indexOf(p[1]!) + 1, name: PHASE_ALIASES[name] ?? name };
+    }
     const t = line.match(/<strong>(\d+)\.\s*([^<]+)<\/strong>/);
-    if (t) topic = { order: Number(t[1]), name: TOPIC_ALIASES[t[2]!.trim()] ?? t[2]!.trim() };
+    if (t) topic = { order: Number(t[1]), name: TOPIC_ALIASES[t[2]!.trim()] ?? t[2]!.trim(), phase };
     if (!topic) continue;
     const n = line.match(/<td align="center">(\d+)<\/td>/);
     if (n && !map.has(Number(n[1]))) map.set(Number(n[1]), topic);
@@ -236,9 +262,43 @@ async function readmeTopics(): Promise<Map<number, Topic>> {
 }
 
 /**
- * Blume folder meta: exact topic label (the folder slug loses `/` and case),
- * curriculum order, and the group's sidebar icon. An unplanned category group
- * (warm-ups) has no README number and sorts at 0, ahead of topic 1, so the
+ * Folder slug for a topic or phase name. Blume reads a leading `<digits>-` on a
+ * folder as a sidebar-order prefix and strips it from the route (`1-d-…` →
+ * `/d-…`), so a slug that would start that way keeps the digits glued to the
+ * next token (`1d-dynamic-programming`).
+ */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .replace(/^(\d+)-/, "$1");
+}
+
+/**
+ * Content folder for a topic, relative to `DOCS`: `(0N-<phase>)/<topic>` for a
+ * planned topic (the phase is a `(group)`, so the route is still `/<topic>`),
+ * bare `<topic>` for an unplanned category group.
+ */
+function topicDir(topic: Topic): string {
+  const slug = slugify(topic.name);
+  return topic.phase ? `${phaseDir(topic.phase)}/${slug}` : slug;
+}
+
+function phaseDir(phase: Phase): string {
+  return `(${String(phase.order).padStart(2, "0")}-${slugify(phase.name)})`;
+}
+
+/** Blume `(group)` meta for a phase: the overview page's heading, in phase order. */
+function phaseMeta(phase: Phase): string {
+  return `import { defineMeta } from "blume";\n\nexport default defineMeta({ title: ${JSON.stringify(`Phase ${phase.order}: ${phase.name}`)}, order: ${phase.order} });\n`;
+}
+
+/**
+ * Blume folder meta for a topic: exact label (the folder slug loses `/` and
+ * case), curriculum order, the sidebar icon, and `display: "group"` so the
+ * topic collapses under its phase heading. An unplanned category group
+ * (warm-ups) has no README number and sorts at 0, ahead of phase 1, so the
  * sidebar opens on the basics.
  */
 function groupMeta(topic: Topic): string {
@@ -246,6 +306,7 @@ function groupMeta(topic: Topic): string {
   if (!icon) console.warn(`no icon for group ${JSON.stringify(topic.name)}: add it to TOPIC_ICONS`);
   const fields = [`title: ${JSON.stringify(topic.name)}`, `order: ${topic.order ?? 0}`];
   if (icon) fields.push(`icon: ${JSON.stringify(icon)}`);
+  fields.push(`display: "group"`);
   return `import { defineMeta } from "blume";\n\nexport default defineMeta({ ${fields.join(", ")} });\n`;
 }
 
@@ -427,6 +488,11 @@ for await (const rel of new Bun.Glob("**/*.{js,py}").scan(WORK)) {
 }
 
 const topics = await readmeTopics();
+// An unplanned problem whose work/ category is also a README topic name (a
+// `Hash Table` warm-up) files under that topic, in its phase, not a second
+// root-level `hash-table/`.
+const topicByName = new Map<string, Topic>();
+for (const topic of topics.values()) topicByName.set(topic.name, topic);
 
 /** Insert a number-free `sidebar.label` into existing frontmatter when missing. */
 function ensureLabel(page: string, h: Header): string {
@@ -464,29 +530,23 @@ for (const rel of (await Array.fromAsync(new Bun.Glob("**/*.mdx").scan(DOCS))).s
 
 const report: [string, string, string][] = [];
 const ordered = [...solutions.values()].sort((a, b) => a.num - b.num);
-const groups = new Map<string, Topic>(); // folder -> topic, for meta.ts
+const groups = new Map<string, Topic>(); // topic folder -> topic, for meta.ts
+const phases = new Map<string, Phase>(); // phase folder -> phase, for meta.ts
 const vacated = new Set<string>(); // folders a page moved out of; removed below if empty
 
 for (const sol of ordered) {
   const langs = Object.keys(sol.code).sort().join("+");
   const workRef = `${sol.num}.${sol.slug} (${langs})`;
-  // <topic>/ folder (a real route segment, so its index.mdx is the topic landing
-  // page) + leetcode-number prefix: numeric sidebar order, prefix stripped from the URL.
-  // An unplanned problem's category may share a folder with a numbered topic
-  // (`Hash Table` warm-ups under topic 1); the numbered one owns the meta.
-  const topic = topics.get(sol.num) ?? { name: sol.category };
-  // Blume reads a leading `<digits>-` on a folder as a sidebar-order prefix and
-  // strips it from the route (`1-d-…` → `/d-…`), so a slug that would start that
-  // way keeps the digits glued to the next token (`1d-dynamic-programming`).
-  const group = topic.name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "")
-    .replace(/^(\d+)-/, "$1");
-  if (groups.get(group)?.order === undefined) groups.set(group, topic);
-  const name = `${group}/${sol.num}-${sol.slug}.mdx`;
+  // (0N-<phase>)/<topic>/ folder (the topic is a real route segment, so its
+  // index.mdx is the landing page) + leetcode-number prefix: numeric sidebar
+  // order, prefix stripped from the URL.
+  const topic = topics.get(sol.num) ?? topicByName.get(sol.category) ?? { name: sol.category };
+  const dir = topicDir(topic);
+  groups.set(dir, topic);
+  if (topic.phase) phases.set(phaseDir(topic.phase), topic.phase);
+  const name = `${dir}/${sol.num}-${sol.slug}.mdx`;
   const existing = pages.get(sol.num);
-  await mkdir(join(DOCS, group), { recursive: true });
+  await mkdir(join(DOCS, dir), { recursive: true });
 
   if (existing) {
     const page = await Bun.file(join(DOCS, existing)).text();
@@ -515,23 +575,36 @@ for (const sol of ordered) {
   }
 }
 
-// Script-owned folder meta: one per live group, rewritten only when it differs.
-for (const [group, topic] of groups) {
-  const path = join(DOCS, group, "meta.ts");
-  const meta = groupMeta(topic);
+// Script-owned folder metas — one per live phase and topic folder — rewritten
+// only when they differ.
+const metas: [label: string, dir: string, meta: string][] = [
+  ...[...phases].map(([dir, phase]): [string, string, string] => [`phase ${phase.order}`, dir, phaseMeta(phase)]),
+  ...[...groups].map(([dir, topic]): [string, string, string] => [`topic ${topic.order ?? "-"}`, dir, groupMeta(topic)]),
+];
+for (const [label, dir, meta] of metas) {
+  const path = join(DOCS, dir, "meta.ts");
   if ((await Bun.file(path).exists()) && (await Bun.file(path).text()) === meta) continue;
   await Bun.write(path, meta);
-  report.push([`topic ${topic.order ?? "-"}`, `${group}/meta.ts`, "written"]);
+  report.push([label, `${dir}/meta.ts`, "written"]);
 }
 
-// A group every page left behind is dead: drop its meta and the folder itself.
-for (const dir of vacated) {
-  if (groups.has(dir)) continue;
-  const left = await readdir(join(DOCS, dir));
-  if (left.some((f) => f !== "meta.ts")) continue;
-  if (left.length) await unlink(join(DOCS, dir, "meta.ts"));
-  await rmdir(join(DOCS, dir));
-  report.push(["", dir, "removed (empty)"]);
+// A folder every page left behind is dead: drop its meta and the folder itself,
+// then the phase folder above it if that emptied too. A folder that still holds
+// anything else (a hand-written index.mdx, another topic) stops the climb.
+for (const start of vacated) {
+  for (let dir = start; dir !== "."; dir = dirname(dir)) {
+    if (groups.has(dir) || phases.has(dir)) break;
+    let left: string[];
+    try {
+      left = await readdir(join(DOCS, dir));
+    } catch {
+      break; // already removed via a sibling's climb
+    }
+    if (left.some((f) => f !== "meta.ts")) break;
+    if (left.length) await unlink(join(DOCS, dir, "meta.ts"));
+    await rmdir(join(DOCS, dir));
+    report.push(["", dir, "removed (empty)"]);
+  }
 }
 
 const w0 = Math.max(...report.map((r) => r[0].length), 9);

apps/docs/blume.config.ts

@@ -7,7 +7,13 @@ export default defineConfig({
     site: "https://prdlk.github.io",
     base: "/leetcode",
   },
+  lastModified: "git",
   content: {
     root: "content",
   },
+  navigation: {
+    sidebar: {
+      display: "flat", // "flat" | "group" | "page"
+    },
+  },
 });

apps/docs/content/(01-linear-structures)/binary-search/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Binary Search", order: 5, icon: "search" });
+export default defineMeta({ title: "Binary Search", order: 5, icon: "search", display: "group" });

apps/docs/content/(01-linear-structures)/hash-table/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Hash Table", order: 1, icon: "hash" });
+export default defineMeta({ title: "Hash Table", order: 1, icon: "hash", display: "group" });

apps/docs/content/(01-linear-structures)/meta.ts

@@ -0,0 +1,3 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({ title: "Phase 1: Linear Structures", order: 1 });

apps/docs/content/(01-linear-structures)/monotonic-stack/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Monotonic Stack", order: 7, icon: "trending-up" });
+export default defineMeta({ title: "Monotonic Stack", order: 7, icon: "trending-up", display: "group" });

apps/docs/content/(01-linear-structures)/prefix-sum/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Prefix Sum", order: 2, icon: "sigma" });
+export default defineMeta({ title: "Prefix Sum", order: 2, icon: "sigma", display: "group" });

apps/docs/content/(01-linear-structures)/sliding-window/index.mdx

@@ -55,7 +55,7 @@ Without an invariant, shrinking the window becomes arbitrary. You no longer know
 The window size never changes. The main task is updating the window state efficiently when one element enters and one leaves.
 :::
 
-![Sliding Window Fixed Size](../../public/sliding-window-fixed-size.svg)
+![Sliding Window Fixed Size](../../../public/sliding-window-fixed-size.svg)
 
 ### 2. Flexible-size windows with a validity rule
 
@@ -63,7 +63,7 @@ The window size never changes. The main task is updating the window state effici
 Here the window expands until invalid, then shrinks until valid again.
 :::
 
-![Flexible-size windows](../../public/sliding-window-flexible.svg)
+![Flexible-size windows](../../../public/sliding-window-flexible.svg)
 
 
 ### 3. Frequency-tracking windows
@@ -72,7 +72,7 @@ Here the window expands until invalid, then shrinks until valid again.
 The difficulty comes from keeping the bookkeeping correct as characters enter and leave.
 :::
 
-![Frequency-tracking windows](../../public/sliding-window-frequency.svg)
+![Frequency-tracking windows](../../../public/sliding-window-frequency.svg)
 
 ## How Sliding Window Differs From Other Two-Pointer Families
 

apps/docs/content/(01-linear-structures)/sliding-window/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Sliding Window", order: 4, icon: "app-window" });
+export default defineMeta({ title: "Sliding Window", order: 4, icon: "app-window", display: "group" });

apps/docs/content/(01-linear-structures)/stack/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Stack", order: 6, icon: "layers" });
+export default defineMeta({ title: "Stack", order: 6, icon: "layers", display: "group" });

apps/docs/content/(01-linear-structures)/two-pointers/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Two Pointers", order: 3, icon: "arrow-left-right" });
+export default defineMeta({ title: "Two Pointers", order: 3, icon: "arrow-left-right", display: "group" });

apps/docs/content/(02-nodal-grid)/hybrid-structures/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Hybrid Structures", order: 9, icon: "combine" });
+export default defineMeta({ title: "Hybrid Structures", order: 9, icon: "combine", display: "group" });

apps/docs/content/(02-nodal-grid)/linked-list/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Linked List", order: 8, icon: "link" });
+export default defineMeta({ title: "Linked List", order: 8, icon: "link", display: "group" });

apps/docs/content/(02-nodal-grid)/matrix-index-math/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Matrix Index Math", order: 10, icon: "grid-3x3" });
+export default defineMeta({ title: "Matrix Index Math", order: 10, icon: "grid-3x3", display: "group" });

apps/docs/content/(02-nodal-grid)/meta.ts

@@ -0,0 +1,3 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({ title: "Phase 2: Nodal & Grid", order: 2 });

apps/docs/content/(03-hierarchical)/binary-search-tree/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Binary Search Tree", order: 13, icon: "git-fork" });
+export default defineMeta({ title: "Binary Search Tree", order: 13, icon: "git-fork", display: "group" });

apps/docs/content/(03-hierarchical)/heap-priority-queue/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Heap / Priority Queue", order: 14, icon: "triangle" });
+export default defineMeta({ title: "Heap / Priority Queue", order: 14, icon: "triangle", display: "group" });

apps/docs/content/(03-hierarchical)/meta.ts

@@ -0,0 +1,3 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({ title: "Phase 3: Hierarchical", order: 3 });

apps/docs/content/(03-hierarchical)/tree-bfs/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Tree BFS", order: 12, icon: "network" });
+export default defineMeta({ title: "Tree BFS", order: 12, icon: "network", display: "group" });

apps/docs/content/(03-hierarchical)/tree-dfs/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Tree DFS", order: 11, icon: "folder-tree" });
+export default defineMeta({ title: "Tree DFS", order: 11, icon: "folder-tree", display: "group" });

apps/docs/content/(03-hierarchical)/trie/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Trie", order: 15, icon: "spell-check" });
+export default defineMeta({ title: "Trie", order: 15, icon: "spell-check", display: "group" });

apps/docs/content/(04-relational)/graph-bfs/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Graph BFS", order: 17, icon: "radar" });
+export default defineMeta({ title: "Graph BFS", order: 17, icon: "radar", display: "group" });

apps/docs/content/(04-relational)/graph-dfs/meta.ts

@@ -1,3 +1,3 @@
 import { defineMeta } from "blume";
 
-export default defineMeta({ title: "Graph DFS", order: 16, icon: "waypoints" });
+export default defineMeta({ title: "Graph DFS", order: 16, icon: "waypoints", display: "group" });

apps/docs/content/(04-relational)/meta.ts

@@ -0,0 +1,3 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({ title: "Phase 4: Relational", order: 4 });