granola-toolkit 0.31.0 → 0.33.0

package/README.md

@@ -275,10 +275,13 @@ You can deep-link into a specific meeting with either:
 
 The initial browser client includes:
 
+- a dedicated folder pane with an explicit All meetings scope
 - a searchable meeting list
+- folder-aware meeting browsing with one-click scope changes
 - a fast local-index warm start for meeting browsing before live documents finish loading
 - sort and updated-date filters
 - quick open by meeting id or title
+- browser URL state that preserves the selected folder, meeting, and tab
 - a focused meeting workspace with notes, transcript, metadata, and raw tabs
 - keyboard-first workspace switching with `1`-`4`, `[` and `]`
 - app-state status from the shared core
@@ -316,6 +319,7 @@ That keeps the current single-package repo simple, while making a future split i
 
 The initial terminal workspace includes:
 
+- a folder scope inside the navigation pane, including an explicit All meetings view
 - a meeting list pane with keyboard navigation
 - a detail pane with notes, transcript, metadata, and raw views
 - an auth session overlay for import, refresh, source switching, and sign-out
@@ -324,7 +328,8 @@ The initial terminal workspace includes:
 
 The main keyboard controls are:
 
-- `j` / `k` or arrow keys to move between meetings
+- `h` / `l`, left / right, or `Tab` to switch between folders and meetings
+- `j` / `k` or arrow keys to move within the active folder or meeting list
 - `/` or `Ctrl+P` to open quick open
 - `a` to open auth session actions
 - `1`-`4` to switch detail tabs

package/dist/cli.js

@@ -1345,6 +1345,7 @@ function renderGranolaTuiMeetingTab(bundle, tab) {
 			`ID: ${summary.id}`,
 			`Created: ${summary.createdAt}`,
 			`Updated: ${summary.updatedAt}`,
+			`Folders: ${summary.folders.length > 0 ? summary.folders.map((folder) => folder.name).join(", ") : "none"}`,
 			`Tags: ${summary.tags.length > 0 ? summary.tags.join(", ") : "none"}`,
 			`Notes source: ${summary.noteContentSource}`,
 			`Transcript loaded: ${summary.transcriptLoaded ? "yes" : "no"}`,
@@ -1360,7 +1361,7 @@ function renderGranolaTuiMeetingTab(bundle, tab) {
 	}
 }
 function buildGranolaTuiSummary(state, meetingSource) {
-	return `auth ${state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | list ${meetingSource}`;
+	return `auth ${state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.folders.loaded ? `${state.folders.count} folders` : "folders pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | list ${meetingSource}`;
 }
 //#endregion
 //#region src/tui/theme.ts
@@ -1657,9 +1658,13 @@ var GranolaTuiWorkspace = class {
 	focused = false;
 	#maxMeetings;
 	#appState;
+	#activePane = "meetings";
 	#detailError = "";
 	#detailScroll = 0;
 	#detailToken = 0;
+	#folderError = "";
+	#folderToken = 0;
+	#folders = [];
 	#listError = "";
 	#listToken = 0;
 	#loadingDetail = false;
@@ -1667,6 +1672,7 @@ var GranolaTuiWorkspace = class {
 	#meetingSource = "live";
 	#meetings = [];
 	#overlay;
+	#selectedFolderId;
 	#selectedMeeting;
 	#selectedMeetingId;
 	#statusMessage = "Loading meetings…";
@@ -1679,11 +1685,13 @@ var GranolaTuiWorkspace = class {
 		this.options = options;
 		this.#appState = app.getState();
 		this.#maxMeetings = options.maxMeetings ?? 200;
+		this.#selectedFolderId = this.#appState.ui.selectedFolderId;
 	}
 	async initialise() {
 		this.#unsubscribe = this.app.subscribe((event) => {
 			this.handleAppUpdate(event);
 		});
+		await this.loadFolders({ setStatus: false });
 		await this.loadMeetings({
 			preferredMeetingId: this.options.initialMeetingId,
 			setStatus: true
@@ -1699,7 +1707,12 @@ var GranolaTuiWorkspace = class {
 	handleAppUpdate(event) {
 		const previousDocumentsLoadedAt = this.#appState.documents.loadedAt;
 		this.#appState = event.state;
-		if (this.#meetingSource === "index" && event.state.documents.loadedAt && event.state.documents.loadedAt !== previousDocumentsLoadedAt && !this.#loadingMeetings) this.loadMeetings({ preferredMeetingId: this.#selectedMeetingId });
+		this.#selectedFolderId = event.state.ui.selectedFolderId;
+		this.#selectedMeetingId = event.state.ui.selectedMeetingId ?? this.#selectedMeetingId;
+		if (this.#meetingSource === "index" && event.state.documents.loadedAt && event.state.documents.loadedAt !== previousDocumentsLoadedAt && !this.#loadingMeetings) (async () => {
+			await this.loadFolders({ setStatus: false });
+			await this.loadMeetings({ preferredMeetingId: this.#selectedMeetingId });
+		})();
 		this.tui.requestRender();
 	}
 	setStatus(message, tone = "info") {
@@ -1712,6 +1725,11 @@ var GranolaTuiWorkspace = class {
 		const selectedIndex = this.#selectedMeetingId ? this.#meetings.findIndex((meeting) => meeting.id === this.#selectedMeetingId) : -1;
 		return selectedIndex >= 0 ? selectedIndex : 0;
 	}
+	normaliseSelectedFolderIndex() {
+		if (!this.#selectedFolderId) return 0;
+		const selectedIndex = this.#folders.findIndex((folder) => folder.id === this.#selectedFolderId);
+		return selectedIndex >= 0 ? selectedIndex + 1 : 0;
+	}
 	ensureMeetingVisible(meeting) {
 		const existingIndex = this.#meetings.findIndex((item) => item.id === meeting.id);
 		if (existingIndex >= 0) this.#meetings[existingIndex] = meeting;
@@ -1721,6 +1739,30 @@ var GranolaTuiWorkspace = class {
 			return left.title.localeCompare(right.title);
 		});
 	}
+	async loadFolders(options = {}) {
+		const token = ++this.#folderToken;
+		this.#folderError = "";
+		if (options.setStatus) this.setStatus(options.forceRefresh ? "Refreshing folders…" : "Loading folders…");
+		try {
+			const result = await this.app.listFolders({
+				forceRefresh: options.forceRefresh,
+				limit: 100
+			});
+			if (token !== this.#folderToken) return;
+			this.#folders = result.folders;
+			if (this.#selectedFolderId && !this.#folders.some((folder) => folder.id === this.#selectedFolderId)) this.#selectedFolderId = void 0;
+			this.#folderError = "";
+		} catch (error) {
+			if (token !== this.#folderToken) return;
+			const message = error instanceof Error ? error.message : String(error);
+			this.#folderError = message;
+			this.#folders = [];
+			this.#selectedFolderId = void 0;
+			this.setStatus(message, "error");
+		} finally {
+			if (token === this.#folderToken) this.tui.requestRender();
+		}
+	}
 	async loadMeetings(options = {}) {
 		const token = ++this.#listToken;
 		this.#loadingMeetings = true;
@@ -1728,6 +1770,7 @@ var GranolaTuiWorkspace = class {
 		if (options.setStatus !== false) this.setStatus(options.forceRefresh ? "Refreshing meetings…" : "Loading meetings…");
 		try {
 			const result = await this.app.listMeetings({
+				folderId: this.#selectedFolderId,
 				forceRefresh: options.forceRefresh,
 				limit: this.#maxMeetings,
 				preferIndex: true
@@ -1736,8 +1779,13 @@ var GranolaTuiWorkspace = class {
 			this.#meetings = result.meetings;
 			this.#meetingSource = result.source;
 			this.#selectedMeetingId = options.preferredMeetingId && this.#meetings.some((meeting) => meeting.id === options.preferredMeetingId) ? options.preferredMeetingId : this.#selectedMeetingId && this.#meetings.some((meeting) => meeting.id === this.#selectedMeetingId) ? this.#selectedMeetingId : this.#meetings[0]?.id;
+			if (!this.#selectedMeetingId) {
+				this.#selectedMeeting = void 0;
+				this.#detailError = "";
+				this.#detailScroll = 0;
+			}
 			this.#listError = "";
-			this.setStatus(result.source === "index" ? "Loaded meetings from the local index" : "Connected to Granola");
+			this.setStatus(result.source === "index" ? "Loaded meetings from the local index" : this.#selectedFolderId ? "Connected to Granola (folder scope)" : "Connected to Granola");
 		} catch (error) {
 			if (token !== this.#listToken) return;
 			const message = error instanceof Error ? error.message : String(error);
@@ -1780,6 +1828,10 @@ var GranolaTuiWorkspace = class {
 	}
 	async refresh(forceRefresh) {
 		try {
+			await this.loadFolders({
+				forceRefresh,
+				setStatus: false
+			});
 			await this.loadMeetings({
 				forceRefresh,
 				preferredMeetingId: this.#selectedMeetingId
@@ -1787,7 +1839,7 @@ var GranolaTuiWorkspace = class {
 			if (this.#selectedMeetingId) await this.loadMeeting(this.#selectedMeetingId, { ensureMeetingVisible: true });
 		} catch {}
 	}
-	async moveSelection(delta) {
+	async moveMeetingSelection(delta) {
 		if (this.#meetings.length === 0) return;
 		const currentIndex = this.normaliseSelectedIndex();
 		const nextIndex = Math.max(0, Math.min(this.#meetings.length - 1, currentIndex + delta));
@@ -1795,6 +1847,33 @@ var GranolaTuiWorkspace = class {
 		if (!nextMeeting || nextMeeting.id === this.#selectedMeetingId) return;
 		await this.loadMeeting(nextMeeting.id);
 	}
+	async moveFolderSelection(delta) {
+		const total = this.#folders.length + 1;
+		const currentIndex = this.normaliseSelectedFolderIndex();
+		const nextIndex = Math.max(0, Math.min(total - 1, currentIndex + delta));
+		const nextFolderId = nextIndex === 0 ? void 0 : this.#folders[nextIndex - 1]?.id;
+		if (nextFolderId === this.#selectedFolderId) return;
+		this.#selectedFolderId = nextFolderId;
+		this.#selectedMeeting = void 0;
+		this.#detailError = "";
+		this.#detailScroll = 0;
+		await this.loadMeetings({
+			preferredMeetingId: this.#selectedMeetingId,
+			setStatus: false
+		});
+		if (this.#selectedMeetingId) {
+			await this.loadMeeting(this.#selectedMeetingId, { ensureMeetingVisible: true });
+			return;
+		}
+		this.tui.requestRender();
+	}
+	async moveSelection(delta) {
+		if (this.#activePane === "folders") {
+			await this.moveFolderSelection(delta);
+			return;
+		}
+		await this.moveMeetingSelection(delta);
+	}
 	currentDetailBody(width) {
 		if (this.#detailError) return wrapBlock(this.#detailError, width);
 		if (this.#loadingDetail && !this.#selectedMeeting) return wrapBlock("Loading meeting details…", width);
@@ -1832,6 +1911,10 @@ var GranolaTuiWorkspace = class {
 	async reloadAfterAuthChange() {
 		const preferredMeetingId = this.#selectedMeeting?.document.id ?? this.#selectedMeetingId;
 		try {
+			await this.loadFolders({
+				forceRefresh: true,
+				setStatus: false
+			});
 			await this.loadMeetings({
 				forceRefresh: true,
 				preferredMeetingId,
@@ -1956,6 +2039,21 @@ var GranolaTuiWorkspace = class {
 			this.openAuthPanel();
 			return;
 		}
+		if (matchesKey(data, "tab")) {
+			this.#activePane = this.#activePane === "folders" ? "meetings" : "folders";
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "left") || matchesKey(data, "h")) {
+			this.#activePane = "folders";
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "right") || matchesKey(data, "l")) {
+			this.#activePane = "meetings";
+			this.tui.requestRender();
+			return;
+		}
 		if (matchesKey(data, "up") || matchesKey(data, "k")) {
 			this.moveSelection(-1);
 			return;
@@ -2021,22 +2119,53 @@ var GranolaTuiWorkspace = class {
 	renderListPane(width, height) {
 		const lines = [];
 		const innerWidth = Math.max(1, width - 2);
-		const header = `${granolaTuiTheme.strong("Meetings")} ${granolaTuiTheme.dim(`(${this.#meetings.length})`)}`;
-		lines.push(padLine(header, innerWidth));
+		const folderEntries = [{
+			id: void 0,
+			label: "All meetings",
+			meta: this.#folders.length > 0 ? `${this.#folders.length} folders` : "global scope"
+		}, ...this.#folders.map((folder) => ({
+			id: folder.id,
+			label: `${folder.isFavourite ? "★ " : ""}${folder.name || folder.id}`,
+			meta: `${folder.documentCount} meetings`
+		}))];
+		const availableRows = Math.max(2, height - 3);
+		const folderWindowSize = Math.min(Math.max(3, Math.min(8, Math.floor(availableRows * .35))), Math.max(1, availableRows - 1));
+		const meetingWindowSize = Math.max(1, availableRows - folderWindowSize);
+		const folderHeader = `${this.#activePane === "folders" ? granolaTuiTheme.accent("Folders") : granolaTuiTheme.strong("Folders")} ${granolaTuiTheme.dim(`(${this.#folders.length})`)}`;
+		lines.push(padLine(folderHeader, innerWidth));
+		if (this.#folderError) {
+			lines.push(...wrapBlock(granolaTuiTheme.error(this.#folderError), innerWidth).slice(0, folderWindowSize));
+			while (lines.length < 1 + folderWindowSize) lines.push(" ".repeat(innerWidth));
+		} else {
+			const selectedFolderIndex = this.normaliseSelectedFolderIndex();
+			const folderStartIndex = Math.max(0, Math.min(selectedFolderIndex - Math.floor(folderWindowSize / 2), folderEntries.length - folderWindowSize));
+			const visibleFolders = folderEntries.slice(folderStartIndex, folderStartIndex + folderWindowSize);
+			for (const [offset, folder] of visibleFolders.entries()) {
+				const selected = folderStartIndex + offset === selectedFolderIndex;
+				const prefix = selected ? "> " : "  ";
+				const maxLabelWidth = Math.max(6, innerWidth - visibleWidth(prefix) - visibleWidth(folder.meta) - 1);
+				const labelBlock = `${prefix}${truncateToWidth(folder.label, maxLabelWidth, "")}`;
+				const line = `${labelBlock}${" ".repeat(Math.max(1, innerWidth - visibleWidth(labelBlock) - visibleWidth(folder.meta)))}${granolaTuiTheme.dim(folder.meta)}`;
+				lines.push(selected ? padLine(granolaTuiTheme.selected(line), innerWidth) : padLine(line, innerWidth));
+			}
+			while (lines.length < 1 + folderWindowSize) lines.push(" ".repeat(innerWidth));
+		}
+		lines.push(padLine(granolaTuiTheme.dim(""), innerWidth));
+		const meetingsHeader = `${this.#activePane === "meetings" ? granolaTuiTheme.accent("Meetings") : granolaTuiTheme.strong("Meetings")} ${granolaTuiTheme.dim(`(${this.#meetings.length})`)}`;
+		lines.push(padLine(meetingsHeader, innerWidth));
 		if (this.#listError) {
-			lines.push(...wrapBlock(granolaTuiTheme.error(this.#listError), innerWidth).slice(0, height - 1));
+			lines.push(...wrapBlock(granolaTuiTheme.error(this.#listError), innerWidth).slice(0, meetingWindowSize));
 			while (lines.length < height) lines.push(" ".repeat(innerWidth));
 			return lines;
 		}
 		if (this.#meetings.length === 0) {
-			lines.push(...wrapBlock("No meetings available yet.", innerWidth).slice(0, height - 1));
+			lines.push(...wrapBlock("No meetings available yet.", innerWidth).slice(0, meetingWindowSize));
 			while (lines.length < height) lines.push(" ".repeat(innerWidth));
 			return lines;
 		}
 		const selectedIndex = this.normaliseSelectedIndex();
-		const windowSize = Math.max(1, height - 1);
-		const startIndex = Math.max(0, Math.min(selectedIndex - Math.floor(windowSize / 2), this.#meetings.length - windowSize));
-		const visibleMeetings = this.#meetings.slice(startIndex, startIndex + windowSize);
+		const startIndex = Math.max(0, Math.min(selectedIndex - Math.floor(meetingWindowSize / 2), this.#meetings.length - meetingWindowSize));
+		const visibleMeetings = this.#meetings.slice(startIndex, startIndex + meetingWindowSize);
 		for (const [offset, meeting] of visibleMeetings.entries()) {
 			const selected = startIndex + offset === selectedIndex;
 			const dateLabel = meeting.updatedAt.slice(0, 10);
@@ -2094,7 +2223,7 @@ var GranolaTuiWorkspace = class {
 		const bodyLines = [];
 		for (let index = 0; index < bodyHeight; index += 1) bodyLines.push(`${padLine(listLines[index] ?? "", listWidth)} | ${padLine(detailLines[index] ?? "", detailWidth)}`);
 		const footerStatus = padLine(toneText(this.#statusTone, this.#statusMessage), width);
-		const footerHints = padLine(granolaTuiTheme.dim("/ quick open  a auth  r refresh  1-4 tabs  PgUp/PgDn scroll  q quit"), width);
+		const footerHints = padLine(granolaTuiTheme.dim("h/l or Tab pane  j/k move  / quick open  a auth  r refresh  1-4 tabs  PgUp/PgDn scroll  q quit"), width);
 		return [
 			headerTitle,
 			headerSummary,
@@ -4204,10 +4333,13 @@ const workspaceTabs = ["notes", "transcript", "metadata", "raw"];
 const state = {
   appState: null,
   detailError: "",
+  folderError: "",
+  folders: [],
   listError: "",
   meetings: [],
   quickOpen: "",
   search: "",
+  selectedFolderId: null,
   selectedMeeting: null,
   selectedMeetingBundle: null,
   selectedMeetingId: null,
@@ -4225,6 +4357,7 @@ const els = {
   detailBody: document.querySelector("[data-detail-body]"),
   detailMeta: document.querySelector("[data-detail-meta]"),
   empty: document.querySelector("[data-empty]"),
+  folderList: document.querySelector("[data-folder-list]"),
   jobsList: document.querySelector("[data-jobs-list]"),
   list: document.querySelector("[data-meeting-list]"),
   noteButton: document.querySelector("[data-export-notes]"),
@@ -4251,6 +4384,7 @@ function parseWorkspaceTab(value) {
 function startupSelection() {
   const params = new URLSearchParams(window.location.search);
   return {
+    folderId: params.get("folder")?.trim() || "",
     meetingId: params.get("meeting")?.trim() || "",
     workspaceTab: parseWorkspaceTab(params.get("tab")),
   };
@@ -4259,6 +4393,12 @@ function startupSelection() {
 function syncBrowserUrl() {
   const url = new URL(window.location.href);
 
+  if (state.selectedFolderId) {
+    url.searchParams.set("folder", state.selectedFolderId);
+  } else {
+    url.searchParams.delete("folder");
+  }
+
   if (state.selectedMeetingId) {
     url.searchParams.set("meeting", state.selectedMeetingId);
   } else {
@@ -4302,6 +4442,11 @@ function syncFilterInputs() {
 function currentFilterSummary() {
   const parts = [];
 
+  if (state.selectedFolderId) {
+    const folder = state.folders.find((candidate) => candidate.id === state.selectedFolderId);
+    parts.push("folder " + (folder ? '"' + folder.name + '"' : '"' + state.selectedFolderId + '"'));
+  }
+
   if (state.search) {
     parts.push('search "' + state.search + '"');
   }
@@ -4344,6 +4489,9 @@ function renderAppState() {
     : appState.index.available
       ? "available"
       : "not built";
+  const folderStatus = appState.folders.loaded
+    ? appState.folders.count + " folders"
+    : "not loaded";
 
   els.appState.innerHTML = [
     '<div class="status-grid">',
@@ -4351,6 +4499,7 @@ function renderAppState() {
     '<div><span class="status-label">View</span><strong>' + escapeHtml(appState.ui.view) + "</strong></div>",
     '<div><span class="status-label">Auth</span><strong>' + escapeHtml(authMode) + "</strong></div>",
     '<div><span class="status-label">Documents</span><strong>' + escapeHtml(docs) + "</strong></div>",
+    '<div><span class="status-label">Folders</span><strong>' + escapeHtml(folderStatus) + "</strong></div>",
     '<div><span class="status-label">Cache</span><strong>' + escapeHtml(cache) + "</strong></div>",
     '<div><span class="status-label">Index</span><strong>' + escapeHtml(indexStatus) + "</strong></div>",
     "</div>",
@@ -4361,6 +4510,50 @@ function renderAppState() {
   renderExportJobs();
 }
 
+function renderFolderList() {
+  if (state.folderError) {
+    els.folderList.innerHTML =
+      '<div class="folder-empty folder-empty--error">' + escapeHtml(state.folderError) + "</div>";
+    return;
+  }
+
+  const buttons = [
+    [
+      '<button class="folder-row"' +
+        (state.selectedFolderId ? "" : ' data-selected="true"') +
+        ' data-folder-id="">',
+      '<span class="folder-row__title">All meetings</span>',
+      '<span class="folder-row__meta">Browse the full meeting list.</span>',
+      "</button>",
+    ].join(""),
+  ];
+
+  for (const folder of state.folders) {
+    buttons.push(
+      [
+        '<button class="folder-row"' +
+          (folder.id === state.selectedFolderId ? ' data-selected="true"' : "") +
+          ' data-folder-id="' +
+          escapeHtml(folder.id) +
+          '">',
+        '<span class="folder-row__title">' +
+          escapeHtml((folder.isFavourite ? "★ " : "") + (folder.name || folder.id)) +
+          "</span>",
+        '<span class="folder-row__meta">' +
+          escapeHtml(String(folder.documentCount) + " meetings") +
+          "</span>",
+        "</button>",
+      ].join(""),
+    );
+  }
+
+  if (buttons.length === 1) {
+    buttons.push('<div class="folder-empty">No folders found.</div>');
+  }
+
+  els.folderList.innerHTML = buttons.join("");
+}
+
 function renderSecurityPanel() {
   els.securityPanel.hidden = !state.serverLocked;
 }
@@ -4504,6 +4697,7 @@ function renderMeetingDetail() {
     "Title: " + (record.meeting.title || record.meeting.id),
     "Created: " + record.meeting.createdAt,
     "Updated: " + record.meeting.updatedAt,
+    "Folders: " + (record.meeting.folders.length ? record.meeting.folders.map((folder) => folder.name).join(", ") : "none"),
     "Tags: " + (record.meeting.tags.length ? record.meeting.tags.join(", ") : "none"),
     "Transcript loaded: " + (record.meeting.transcriptLoaded ? "yes" : "no"),
   ].join("\n");
@@ -4613,6 +4807,10 @@ function buildMeetingsQuery(limit = 100, refresh = false) {
     params.set("updatedTo", state.updatedTo);
   }
 
+  if (state.selectedFolderId) {
+    params.set("folderId", state.selectedFolderId);
+  }
+
   if (refresh) {
     params.set("refresh", "true");
   }
@@ -4620,6 +4818,39 @@ function buildMeetingsQuery(limit = 100, refresh = false) {
   return "?" + params.toString();
 }
 
+async function loadFolders(options = {}) {
+  const refresh = options.refresh === true;
+
+  try {
+    state.folderError = "";
+    const params = new URLSearchParams();
+    params.set("limit", "100");
+    if (refresh) {
+      params.set("refresh", "true");
+    }
+
+    const payload = await fetchJson("/folders?" + params.toString());
+    state.folders = payload.folders || [];
+    if (
+      state.selectedFolderId &&
+      !state.folders.some((folder) => folder.id === state.selectedFolderId)
+    ) {
+      state.selectedFolderId = null;
+    }
+  } catch (error) {
+    if (error.authRequired) {
+      throw error;
+    }
+
+    state.folderError = error instanceof Error ? error.message : String(error);
+    state.folders = [];
+    state.selectedFolderId = null;
+  }
+
+  renderFolderList();
+  syncBrowserUrl();
+}
+
 async function loadMeetings(options = {}) {
   const preferredMeetingId = options.preferredMeetingId || state.selectedMeetingId;
   const refresh = options.refresh === true;
@@ -4683,10 +4914,12 @@ async function quickOpenMeeting() {
   try {
     state.quickOpen = query;
     const payload = await fetchJson("/meetings/resolve?q=" + encodeURIComponent(query));
+    state.selectedFolderId = payload.meeting?.meeting?.folders?.[0]?.id || null;
     state.search = "";
     state.updatedFrom = "";
     state.updatedTo = "";
     syncFilterInputs();
+    renderFolderList();
     await loadMeetings({
       preferredMeetingId: payload.document.id,
     });
@@ -4701,11 +4934,9 @@ async function quickOpenMeeting() {
 async function refreshAll(forceLiveMeetings = false) {
   setStatus("Refreshing…", "busy");
   try {
-    const [appState, authState] = await Promise.all([
-      fetchJson("/state"),
-      fetchJson("/auth/status"),
-      loadMeetings({ refresh: forceLiveMeetings }),
-    ]);
+    await loadFolders({ refresh: forceLiveMeetings });
+    const [appState, authState] = await Promise.all([fetchJson("/state"), fetchJson("/auth/status")]);
+    await loadMeetings({ refresh: forceLiveMeetings });
     state.serverLocked = false;
     state.appState = {
       ...appState,
@@ -4856,17 +5087,40 @@ async function lockServer() {
 
   state.serverLocked = true;
   state.appState = null;
+  state.folders = [];
   state.meetings = [];
+  state.selectedFolderId = null;
   state.selectedMeeting = null;
   state.selectedMeetingBundle = null;
   state.detailError = "";
+  state.folderError = "";
   els.serverPassword.value = "";
   renderSecurityPanel();
+  renderFolderList();
   renderMeetingList();
   renderMeetingDetail();
   setStatus("Server locked", "error");
 }
 
+els.folderList.addEventListener("click", (event) => {
+  if (!(event.target instanceof Element)) {
+    return;
+  }
+
+  const button = event.target.closest("[data-folder-id]");
+  if (!button) {
+    return;
+  }
+
+  const nextFolderId = button.dataset.folderId || null;
+  state.selectedFolderId = nextFolderId;
+  state.selectedMeetingId = null;
+  state.selectedMeeting = null;
+  state.selectedMeetingBundle = null;
+  renderFolderList();
+  void loadMeetings();
+});
+
 els.list.addEventListener("click", (event) => {
   if (!(event.target instanceof Element)) {
     return;
@@ -5071,6 +5325,7 @@ document.addEventListener("keydown", (event) => {
 });
 
 const initialSelection = startupSelection();
+state.selectedFolderId = initialSelection.folderId || null;
 state.selectedMeetingId = initialSelection.meetingId || null;
 state.workspaceTab = initialSelection.workspaceTab;
 
@@ -5086,9 +5341,12 @@ events.addEventListener("state.updated", (event) => {
     payload.state.documents?.loadedAt &&
     payload.state.documents.loadedAt !== previousLoadedAt
   ) {
-    void loadMeetings({
-      preferredMeetingId: state.selectedMeetingId,
-    });
+    void (async () => {
+      await loadFolders();
+      await loadMeetings({
+        preferredMeetingId: state.selectedMeetingId,
+      });
+    })();
   }
 });
 events.addEventListener("error", () => {
@@ -5097,6 +5355,7 @@ events.addEventListener("error", () => {
 
 syncFilterInputs();
 renderSecurityPanel();
+renderFolderList();
 
 void refreshAll().catch((error) => {
   setStatus("Error", "error");
@@ -5111,7 +5370,7 @@ const granolaWebMarkup = String.raw`
   <aside class="pane sidebar">
     <section class="hero">
       <h1>Granola Toolkit</h1>
-      <p>Browser workspace for meetings, notes, transcripts, and export flows on top of one local server instance.</p>
+      <p>Browser workspace for folders, meetings, notes, transcripts, and export flows on top of one local server instance.</p>
       <input class="search" data-search placeholder="Search meetings, ids, or tags" />
       <div class="field-row field-row--inline">
         <label>
@@ -5133,6 +5392,13 @@ const granolaWebMarkup = String.raw`
         <input class="field-input" data-updated-to type="date" />
       </label>
     </section>
+    <section class="folder-panel">
+      <div class="folder-panel__head">
+        <h2>Folders</h2>
+        <p>Pick a folder to scope the meeting browser, or stay on All meetings.</p>
+      </div>
+      <div class="folder-list" data-folder-list></div>
+    </section>
     <section class="toolbar">
       <div>
         <p>Meetings are loaded from the shared server state so this view can later coexist with the terminal UI.</p>
@@ -5254,11 +5520,11 @@ body {
 
 .sidebar {
   display: grid;
-  grid-template-rows: auto auto 1fr;
+  grid-template-rows: auto auto auto 1fr;
   overflow: hidden;
 }
 
-.hero, .toolbar, .detail-head {
+.hero, .toolbar, .detail-head, .folder-panel {
   padding: 22px 24px;
   border-bottom: 1px solid var(--line);
 }
@@ -5315,6 +5581,68 @@ body {
   overflow: auto;
 }
 
+.folder-panel {
+  display: grid;
+  gap: 14px;
+}
+
+.folder-panel__head h2 {
+  margin: 0;
+  font-size: 0.92rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.folder-panel__head p {
+  margin: 6px 0 0;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+.folder-list {
+  display: grid;
+  gap: 10px;
+}
+
+.folder-row {
+  width: 100%;
+  display: grid;
+  gap: 4px;
+  text-align: left;
+  padding: 12px 14px;
+  border: 1px solid transparent;
+  border-radius: 16px;
+  background: rgba(255, 255, 255, 0.72);
+  color: inherit;
+  cursor: pointer;
+  transition: transform 140ms ease, border-color 140ms ease, background 140ms ease;
+}
+
+.folder-row:hover,
+.folder-row[data-selected="true"] {
+  transform: translateY(-1px);
+  border-color: rgba(163, 79, 47, 0.26);
+  background: var(--panel-strong);
+}
+
+.folder-row__title {
+  font-weight: 700;
+}
+
+.folder-row__meta {
+  color: var(--muted);
+  font-size: 0.88rem;
+}
+
+.folder-empty {
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+
+.folder-empty--error {
+  color: var(--error);
+}
+
 .meeting-row {
   width: 100%;
   display: grid;
@@ -6174,7 +6502,11 @@ function printWebRoutes() {
 	console.log("  GET  /auth/status");
 	console.log("  GET  /state");
 	console.log("  GET  /events");
+	console.log("  GET  /folders");
+	console.log("  GET  /folders/resolve?q=<query>");
+	console.log("  GET  /folders/:id");
 	console.log("  GET  /meetings");
+	console.log("  GET  /meetings?folderId=<id>");
 	console.log("  GET  /meetings/:id");
 	console.log("  GET  /exports/jobs");
 	console.log("  POST /auth/login");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Toolkit for exporting and working with Granola meetings, notes, and transcripts",
   "keywords": [
     "cli",