granola-toolkit 0.30.0 → 0.31.0

package/README.md

@@ -35,6 +35,7 @@ granola --help
 granola attach --help
 granola auth login
 granola exports --help
+granola folder --help
 granola meeting --help
 granola notes --help
 granola serve --help
@@ -52,6 +53,7 @@ vp pack
 node dist/cli.js --help
 node dist/cli.js attach --help
 node dist/cli.js exports --help
+node dist/cli.js folder --help
 node dist/cli.js meeting --help
 node dist/cli.js notes --help
 node dist/cli.js serve --help
@@ -94,8 +96,11 @@ node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
 Inspect individual meetings:
 
 ```bash
+granola folder list
+granola folder view Team
 granola meeting list --limit 10
 granola meeting list --search planning
+granola meeting list --folder Team
 granola meeting view 1234abcd
 granola meeting notes 1234abcd
 granola meeting transcript 1234abcd --format json
@@ -201,6 +206,24 @@ The machine-readable `export` command includes:
 - structured note data plus rendered Markdown
 - structured transcript data plus rendered transcript text when available
 
+### Folders
+
+`folder` exposes Granola document lists as a first-class concept instead of leaving meetings in one flat global list.
+
+The flow is:
+
+1. reuse the shared auth path that `notes` and `meeting` already use
+2. call Granola's document-list API, with `v2` first and `v1` fallback
+3. normalise folder metadata and document membership into shared folder records
+4. attach folder membership to meetings in the shared app core
+5. let folder commands and meeting filters resolve folders by id, prefix, or unique name
+
+The current CLI surface includes:
+
+- `folder list`
+- `folder view <id|name>`
+- `meeting list --folder <id|name>`
+
 ### Server
 
 `serve` starts a long-lived local `Granola Toolkit` server on one shared app instance.
@@ -214,7 +237,11 @@ The initial server API includes:
 - `GET /auth/status`
 - `GET /state`
 - `GET /events` for server-sent state updates
+- `GET /folders`
+- `GET /folders/resolve?q=<query>`
+- `GET /folders/:id`
 - `GET /meetings`
+- `GET /meetings?folderId=<id>` for folder-scoped meeting lists
 - `GET /meetings?refresh=true` to bypass the local meeting index and force a live refresh
 - `GET /meetings/resolve?q=<query>`
 - `GET /meetings/:id`

package/dist/cli.js

@@ -22,6 +22,8 @@ const granolaTransportPaths = {
 	exportJobs: "/exports/jobs",
 	exportNotes: "/exports/notes",
 	exportTranscripts: "/exports/transcripts",
+	folderResolve: "/folders/resolve",
+	folders: "/folders",
 	health: "/health",
 	meetingResolve: "/meetings/resolve",
 	meetings: "/meetings",
@@ -48,6 +50,7 @@ function granolaMeetingResolvePath(query, options = {}) {
 }
 function granolaMeetingsPath(options = {}) {
 	return appendSearchParams(granolaTransportPaths.meetings, {
+		folderId: options.folderId,
 		limit: options.limit,
 		refresh: options.forceRefresh ? "true" : void 0,
 		search: options.search,
@@ -56,6 +59,19 @@ function granolaMeetingsPath(options = {}) {
 		updatedTo: options.updatedTo
 	});
 }
+function granolaFolderPath(id) {
+	return `${granolaTransportPaths.folders}/${encodeURIComponent(id)}`;
+}
+function granolaFolderResolvePath(query) {
+	return appendSearchParams(granolaTransportPaths.folderResolve, { q: query });
+}
+function granolaFoldersPath(options = {}) {
+	return appendSearchParams(granolaTransportPaths.folders, {
+		limit: options.limit,
+		refresh: options.forceRefresh ? "true" : void 0,
+		search: options.search
+	});
+}
 function granolaExportJobsPath(options = {}) {
 	return appendSearchParams(granolaTransportPaths.exportJobs, { limit: options.limit });
 }
@@ -131,7 +147,7 @@ var GranolaServerClient = class GranolaServerClient {
 		}) });
 		if (!infoResponse.ok) throw await responseError(infoResponse);
 		const info = await infoResponse.json();
-		if (info.protocolVersion !== 1) throw new Error(`unsupported Granola transport protocol: expected 1, got ${info.protocolVersion}`);
+		if (info.protocolVersion !== 2) throw new Error(`unsupported Granola transport protocol: expected 2, got ${info.protocolVersion}`);
 		const response = await fetchImpl(new URL(granolaTransportPaths.state, url), { headers: mergeHeaders({
 			...options.password?.trim() ? { "x-granola-password": options.password.trim() } : {},
 			accept: "application/json"
@@ -181,6 +197,15 @@ var GranolaServerClient = class GranolaServerClient {
 			method: "POST"
 		});
 	}
+	async listFolders(options = {}) {
+		return await this.requestJson(granolaFoldersPath(options));
+	}
+	async getFolder(id) {
+		return await this.requestJson(granolaFolderPath(id));
+	}
+	async findFolder(query) {
+		return await this.requestJson(granolaFolderResolvePath(query));
+	}
 	async listMeetings(options = {}) {
 		return await this.requestJson(granolaMeetingsPath(options));
 	}
@@ -1075,6 +1100,10 @@ function matchesMeetingSearch(document, search) {
 		...document.tags
 	].some((value) => value.toLowerCase().includes(query));
 }
+function matchesMeetingFolders(documentId, folderId, foldersByDocumentId) {
+	if (!folderId) return true;
+	return (foldersByDocumentId?.get(documentId) ?? []).some((folder) => folder.id === folderId);
+}
 function matchesMeetingSummarySearch(meeting, search) {
 	const query = search.trim().toLowerCase();
 	if (!query) return true;
@@ -1084,6 +1113,9 @@ function matchesMeetingSummarySearch(meeting, search) {
 		...meeting.tags
 	].some((value) => value.toLowerCase().includes(query));
 }
+function meetingFolders(meeting) {
+	return Array.isArray(meeting.folders) ? meeting.folders : [];
+}
 function parseDateFilter(value, label) {
 	const trimmed = value?.trim();
 	if (!trimmed) return;
@@ -1110,7 +1142,7 @@ function matchesMeetingSummaryUpdatedRange(meeting, updatedFrom, updatedTo) {
 	if (to != null && updatedAt > to) return false;
 	return true;
 }
-function truncate(value, width) {
+function truncate$1(value, width) {
 	if (value.length <= width) return value.padEnd(width);
 	return `${value.slice(0, Math.max(0, width - 1))}…`;
 }
@@ -1126,11 +1158,12 @@ function formatTranscriptLines(transcript) {
 	if (!transcript || transcript.segments.length === 0) return "";
 	return transcript.segments.map((segment) => `[${formatTimestampForTranscript(segment.startTimestamp)}] ${segment.speaker}: ${segment.text}`).join("\n");
 }
-function buildMeetingSummary(document, cacheData) {
+function buildMeetingSummary(document, cacheData, folders = []) {
 	const note = buildNoteExport(document);
 	const transcript = buildMeetingTranscript(document, cacheData);
 	return {
 		createdAt: document.createdAt,
+		folders: folders.map((folder) => ({ ...folder })),
 		id: document.id,
 		noteContentSource: note.contentSource,
 		tags: [...document.tags],
@@ -1140,12 +1173,13 @@ function buildMeetingSummary(document, cacheData) {
 		updatedAt: latestDocumentTimestamp(document)
 	};
 }
-function buildMeetingRecord(document, cacheData) {
+function buildMeetingRecord(document, cacheData, folders = []) {
 	const note = buildNoteExport(document);
 	const transcript = buildMeetingTranscript(document, cacheData);
 	return {
 		meeting: {
 			createdAt: document.createdAt,
+			folders: folders.map((folder) => ({ ...folder })),
 			id: document.id,
 			noteContentSource: note.contentSource,
 			tags: [...document.tags],
@@ -1163,13 +1197,14 @@ function buildMeetingRecord(document, cacheData) {
 function listMeetings(documents, options = {}) {
 	const limit = options.limit ?? 20;
 	const sort = options.sort ?? "updated-desc";
-	return documents.filter((document) => options.search ? matchesMeetingSearch(document, options.search) : true).filter((document) => matchesUpdatedRange(document, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingDocumentsBySort(left, right, sort)).slice(0, limit).map((document) => buildMeetingSummary(document, options.cacheData));
+	return documents.filter((document) => options.search ? matchesMeetingSearch(document, options.search) : true).filter((document) => matchesMeetingFolders(document.id, options.folderId, options.foldersByDocumentId)).filter((document) => matchesUpdatedRange(document, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingDocumentsBySort(left, right, sort)).slice(0, limit).map((document) => buildMeetingSummary(document, options.cacheData, options.foldersByDocumentId?.get(document.id)));
 }
 function filterMeetingSummaries(meetings, options = {}) {
 	const limit = options.limit ?? 20;
 	const sort = options.sort ?? "updated-desc";
-	return meetings.filter((meeting) => options.search ? matchesMeetingSummarySearch(meeting, options.search) : true).filter((meeting) => matchesMeetingSummaryUpdatedRange(meeting, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingSummariesBySort(left, right, sort)).slice(0, limit).map((meeting) => ({
+	return meetings.filter((meeting) => options.folderId ? meetingFolders(meeting).some((folder) => folder.id === options.folderId) : true).filter((meeting) => options.search ? matchesMeetingSummarySearch(meeting, options.search) : true).filter((meeting) => matchesMeetingSummaryUpdatedRange(meeting, options.updatedFrom, options.updatedTo)).sort((left, right) => compareMeetingSummariesBySort(left, right, sort)).slice(0, limit).map((meeting) => ({
 		...meeting,
+		folders: meetingFolders(meeting).map((folder) => ({ ...folder })),
 		tags: [...meeting.tags]
 	}));
 }
@@ -1206,14 +1241,18 @@ function renderMeetingList(meetings, format = "text") {
 		case "text": break;
 	}
 	if (meetings.length === 0) return "No meetings found\n";
-	const lines = [`${"ID".padEnd(10)} ${"DATE".padEnd(10)} ${"TITLE".padEnd(42)} ${"NOTE".padEnd(18)} TRANSCRIPT`, `${"-".repeat(10)} ${"-".repeat(10)} ${"-".repeat(42)} ${"-".repeat(18)} ${"-".repeat(10)}`];
-	for (const meeting of meetings) lines.push([
-		meeting.id.slice(0, 8).padEnd(10),
-		formatMeetingDate(meeting.updatedAt || meeting.createdAt).padEnd(10),
-		truncate(meeting.title || meeting.id, 42),
-		truncate(meeting.noteContentSource, 18),
-		formatTranscriptStatus(meeting)
-	].join(" "));
+	const lines = [`${"ID".padEnd(10)} ${"DATE".padEnd(10)} ${"TITLE".padEnd(34)} ${"FOLDERS".padEnd(18)} ${"NOTE".padEnd(18)} TRANSCRIPT`, `${"-".repeat(10)} ${"-".repeat(10)} ${"-".repeat(34)} ${"-".repeat(18)} ${"-".repeat(18)} ${"-".repeat(10)}`];
+	for (const meeting of meetings) {
+		const folderLabel = meetingFolders(meeting).length === 0 ? "-" : meetingFolders(meeting).length === 1 ? meetingFolders(meeting)[0].name : `${meetingFolders(meeting)[0].name} +${meetingFolders(meeting).length - 1}`;
+		lines.push([
+			meeting.id.slice(0, 8).padEnd(10),
+			formatMeetingDate(meeting.updatedAt || meeting.createdAt).padEnd(10),
+			truncate$1(meeting.title || meeting.id, 34),
+			truncate$1(folderLabel, 18),
+			truncate$1(meeting.noteContentSource, 18),
+			formatTranscriptStatus(meeting)
+		].join(" "));
+	}
 	return `${lines.join("\n").trimEnd()}\n`;
 }
 function renderMeetingView(record, format = "text") {
@@ -1223,6 +1262,7 @@ function renderMeetingView(record, format = "text") {
 		case "text": break;
 	}
 	const tags = record.meeting.tags.length > 0 ? record.meeting.tags.join(", ") : "(none)";
+	const folders = meetingFolders(record.meeting).length > 0 ? meetingFolders(record.meeting).map((folder) => folder.name).join(", ") : "(none)";
 	const transcriptStatus = !record.meeting.transcriptLoaded ? "cache not loaded" : record.meeting.transcriptSegmentCount === 0 ? "no transcript segments" : `${record.meeting.transcriptSegmentCount} segment(s)`;
 	return `${[
 		`# ${record.meeting.title || record.meeting.id}`,
@@ -1231,6 +1271,7 @@ function renderMeetingView(record, format = "text") {
 		`Created: ${record.meeting.createdAt || "-"}`,
 		`Updated: ${record.meeting.updatedAt || "-"}`,
 		`Tags: ${tags}`,
+		`Folders: ${folders}`,
 		`Note source: ${record.meeting.noteContentSource}`,
 		`Transcript: ${transcriptStatus}`,
 		"",
@@ -2591,10 +2632,39 @@ function parseDocument(value) {
 		updatedAt: stringValue(record.updated_at)
 	};
 }
+function parseFolderDocumentIds(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((item) => {
+		if (typeof item === "string") return item;
+		const record = asRecord(item);
+		if (!record) return "";
+		return stringValue(record.id) || stringValue(record.document_id);
+	}).filter(Boolean);
+}
+function parseFolder(value) {
+	const record = asRecord(value);
+	if (!record) throw new Error("folder payload is not an object");
+	const createdAt = stringValue(record.created_at);
+	const updatedAt = stringValue(record.updated_at) || createdAt;
+	const name = stringValue(record.name) || stringValue(record.title);
+	const documents = parseFolderDocumentIds(record.documents);
+	const documentIds = documents.length > 0 ? documents : parseFolderDocumentIds(record.document_ids);
+	return {
+		createdAt,
+		description: stringValue(record.description) || void 0,
+		documentIds,
+		id: stringValue(record.id),
+		isFavourite: Boolean(record.is_favourite),
+		name,
+		updatedAt,
+		workspaceId: stringValue(record.workspace_id) || void 0
+	};
+}
 //#endregion
 //#region src/client/granola.ts
 const DEFAULT_CLIENT_VERSION = "5.354.0";
 const DOCUMENTS_URL = "https://api.granola.ai/v2/get-documents";
+const FOLDERS_URLS = ["https://api.granola.ai/v2/get-document-lists", "https://api.granola.ai/v1/get-document-lists"];
 function resolveClientVersion(value) {
 	return value?.trim() || process.env.GRANOLA_CLIENT_VERSION?.trim() || DEFAULT_CLIENT_VERSION;
 }
@@ -2640,6 +2710,29 @@ var GranolaApiClient = class {
 		}
 		return documents;
 	}
+	async listFolders(options) {
+		let lastError;
+		for (const foldersUrl of FOLDERS_URLS) {
+			const response = await this.httpClient.postJson(foldersUrl, {}, {
+				headers: {
+					"User-Agent": `Granola/${this.clientVersion}`,
+					"X-Client-Version": this.clientVersion
+				},
+				timeoutMs: options.timeoutMs
+			});
+			if (response.status === 404) {
+				lastError = /* @__PURE__ */ new Error(`failed to get folders: ${response.status} ${response.statusText}`);
+				continue;
+			}
+			if (!response.ok) {
+				const body = (await response.text()).slice(0, 500);
+				throw new Error(`failed to get folders: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+			}
+			const payload = await response.json();
+			return (Array.isArray(payload) ? payload : Array.isArray(payload.lists) ? payload.lists : Array.isArray(payload.document_lists) ? payload.document_lists : []).map(parseFolder);
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("failed to get folders");
+	}
 };
 //#endregion
 //#region src/client/http.ts
@@ -2826,8 +2919,121 @@ function createDefaultExportJobStore() {
 	return new FileExportJobStore();
 }
 //#endregion
+//#region src/folders.ts
+function truncate(value, width) {
+	if (value.length <= width) return value.padEnd(width);
+	return `${value.slice(0, Math.max(0, width - 1))}…`;
+}
+function compareFolders(left, right) {
+	return right.updatedAt.localeCompare(left.updatedAt) || compareStrings(left.name || left.id, right.name || right.id) || compareStrings(left.id, right.id);
+}
+function matchesFolderSearch(folder, search) {
+	const query = search.trim().toLowerCase();
+	if (!query) return true;
+	return [
+		folder.id,
+		folder.name,
+		folder.description ?? "",
+		folder.workspaceId ?? ""
+	].some((value) => value.toLowerCase().includes(query));
+}
+function formatFolderDate(value) {
+	return value.trim().slice(0, 10) || "-";
+}
+function buildFolderSummary(folder) {
+	return {
+		createdAt: folder.createdAt,
+		description: folder.description,
+		documentCount: folder.documentIds.length,
+		id: folder.id,
+		isFavourite: folder.isFavourite,
+		name: folder.name,
+		updatedAt: folder.updatedAt,
+		workspaceId: folder.workspaceId
+	};
+}
+function buildFolderRecord(folder, meetings) {
+	return {
+		...buildFolderSummary(folder),
+		documentIds: [...folder.documentIds],
+		meetings: meetings.map((meeting) => ({
+			...meeting,
+			folders: meeting.folders.map((candidate) => ({ ...candidate })),
+			tags: [...meeting.tags]
+		}))
+	};
+}
+function filterFolders(folders, options = {}) {
+	const limit = options.limit ?? 20;
+	return folders.filter((folder) => options.search ? matchesFolderSearch(folder, options.search) : true).sort(compareFolders).slice(0, limit).map((folder) => ({ ...folder }));
+}
+function resolveFolder(folders, id) {
+	const exactMatch = folders.find((folder) => folder.id === id);
+	if (exactMatch) return exactMatch;
+	const matches = folders.filter((folder) => folder.id.startsWith(id));
+	if (matches.length === 1) return matches[0];
+	if (matches.length > 1) throw new Error(`ambiguous folder id: ${id}`);
+	throw new Error(`folder not found: ${id}`);
+}
+function resolveFolderQuery(folders, query) {
+	const trimmed = query.trim();
+	if (!trimmed) throw new Error("folder query is required");
+	const lower = trimmed.toLowerCase();
+	const exactId = folders.find((folder) => folder.id === trimmed);
+	if (exactId) return exactId;
+	const exactNameMatches = folders.filter((folder) => folder.name.toLowerCase() === lower);
+	if (exactNameMatches.length === 1) return exactNameMatches[0];
+	const prefixMatches = folders.filter((folder) => folder.id.startsWith(trimmed));
+	if (prefixMatches.length === 1) return prefixMatches[0];
+	const nameMatches = folders.filter((folder) => folder.name.toLowerCase().includes(lower)).sort(compareFolders);
+	if (nameMatches.length === 1) return nameMatches[0];
+	if (exactNameMatches.length > 1 || prefixMatches.length > 1 || nameMatches.length > 1) throw new Error(`ambiguous folder query: ${trimmed}`);
+	throw new Error(`folder not found: ${trimmed}`);
+}
+function renderFolderList(folders, format = "text") {
+	switch (format) {
+		case "json": return toJson(folders);
+		case "yaml": return toYaml(folders);
+		case "text": break;
+	}
+	if (folders.length === 0) return "No folders found\n";
+	const lines = [`${"ID".padEnd(10)} ${"COUNT".padEnd(7)} ${"UPDATED".padEnd(10)} NAME`, `${"-".repeat(10)} ${"-".repeat(7)} ${"-".repeat(10)} ${"-".repeat(42)}`];
+	for (const folder of folders) {
+		const name = `${folder.isFavourite ? "★ " : ""}${folder.name || folder.id}`;
+		lines.push([
+			folder.id.slice(0, 8).padEnd(10),
+			String(folder.documentCount).padEnd(7),
+			formatFolderDate(folder.updatedAt || folder.createdAt).padEnd(10),
+			truncate(name, 42)
+		].join(" "));
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function renderFolderView(folder, format = "text") {
+	switch (format) {
+		case "json": return toJson(folder);
+		case "yaml": return toYaml(folder);
+		case "text": break;
+	}
+	const lines = [
+		`# ${folder.name || folder.id}`,
+		"",
+		`ID: ${folder.id}`,
+		`Created: ${folder.createdAt || "-"}`,
+		`Updated: ${folder.updatedAt || "-"}`,
+		`Documents: ${folder.documentCount}`,
+		`Favourite: ${folder.isFavourite ? "yes" : "no"}`,
+		`Workspace: ${folder.workspaceId || "-"}`
+	];
+	if (folder.description) lines.push(`Description: ${folder.description}`);
+	lines.push("", "## Meetings", "");
+	lines.push(renderMeetingList(folder.meetings, "text").trimEnd());
+	lines.push("");
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+//#endregion
 //#region src/meeting-index.ts
-const MEETING_INDEX_VERSION = 1;
+const MEETING_INDEX_VERSION = 2;
 var FileMeetingIndexStore = class {
 	constructor(filePath = defaultMeetingIndexFilePath()) {
 		this.filePath = filePath;
@@ -2838,6 +3044,7 @@ var FileMeetingIndexStore = class {
 			if (!parsed || parsed.version !== MEETING_INDEX_VERSION || !Array.isArray(parsed.meetings)) return [];
 			return parsed.meetings.map((meeting) => ({
 				...meeting,
+				folders: Array.isArray(meeting.folders) ? meeting.folders.map((folder) => ({ ...folder })) : [],
 				tags: [...meeting.tags]
 			}));
 		} catch {
@@ -2849,6 +3056,7 @@ var FileMeetingIndexStore = class {
 		const payload = {
 			meetings: meetings.map((meeting) => ({
 				...meeting,
+				folders: Array.isArray(meeting.folders) ? meeting.folders.map((folder) => ({ ...folder })) : [],
 				tags: [...meeting.tags]
 			})),
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2877,6 +3085,16 @@ function cloneExportState(state) {
 function cloneExportJob(job) {
 	return { ...job };
 }
+function cloneFolderSummary(folder) {
+	return { ...folder };
+}
+function cloneMeetingSummary(meeting) {
+	return {
+		...meeting,
+		folders: Array.isArray(meeting.folders) ? meeting.folders.map((folder) => cloneFolderSummary(folder)) : [],
+		tags: [...meeting.tags]
+	};
+}
 function cloneState(state) {
 	return {
 		auth: { ...state.auth },
@@ -2887,6 +3105,7 @@ function cloneState(state) {
 			transcripts: { ...state.config.transcripts }
 		},
 		documents: { ...state.documents },
+		folders: { ...state.folders },
 		exports: {
 			jobs: state.exports.jobs.map((job) => cloneExportJob(job)),
 			notes: cloneExportState(state.exports.notes),
@@ -2915,6 +3134,10 @@ function defaultState(config, auth, surface) {
 			count: 0,
 			loaded: false
 		},
+		folders: {
+			count: 0,
+			loaded: false
+		},
 		exports: { jobs: [] },
 		index: {
 			available: false,
@@ -2931,6 +3154,7 @@ function defaultState(config, auth, surface) {
 var GranolaApp = class {
 	#cacheData;
 	#cacheResolved = false;
+	#folders;
 	#granolaClient;
 	#documents;
 	#meetingIndex;
@@ -2942,10 +3166,7 @@ var GranolaApp = class {
 		this.deps = deps;
 		this.#state = defaultState(config, deps.auth, options.surface ?? "cli");
 		this.#state.exports.jobs = (deps.exportJobs ?? []).map((job) => cloneExportJob(job));
-		this.#meetingIndex = (deps.meetingIndex ?? []).map((meeting) => ({
-			...meeting,
-			tags: [...meeting.tags]
-		}));
+		this.#meetingIndex = (deps.meetingIndex ?? []).map((meeting) => cloneMeetingSummary(meeting));
 		this.#state.index = {
 			available: this.#meetingIndex.length > 0,
 			filePath: defaultMeetingIndexFilePath(),
@@ -2971,16 +3192,21 @@ var GranolaApp = class {
 		this.emitStateUpdate();
 		return this.getState();
 	}
-	resetDocumentsState() {
+	resetRemoteState() {
 		this.#granolaClient = void 0;
+		this.#folders = void 0;
 		this.#documents = void 0;
 		this.#state.documents = {
 			count: 0,
 			loaded: false
 		};
+		this.#state.folders = {
+			count: 0,
+			loaded: false
+		};
 	}
 	applyAuthState(auth, options = {}) {
-		if (options.resetDocuments) this.resetDocumentsState();
+		if (options.resetDocuments) this.resetRemoteState();
 		this.#state.auth = { ...auth };
 		if (options.view) this.#state.ui = {
 			...this.#state.ui,
@@ -2990,10 +3216,7 @@ var GranolaApp = class {
 		return { ...auth };
 	}
 	async persistMeetingIndex(meetings) {
-		this.#meetingIndex = meetings.map((meeting) => ({
-			...meeting,
-			tags: [...meeting.tags]
-		}));
+		this.#meetingIndex = meetings.map((meeting) => cloneMeetingSummary(meeting));
 		this.#state.index = {
 			available: this.#meetingIndex.length > 0,
 			filePath: this.#state.index.filePath,
@@ -3007,8 +3230,10 @@ var GranolaApp = class {
 	async refreshMeetingIndexFromLiveData() {
 		const cacheData = await this.loadCache();
 		const documents = await this.listDocuments();
+		const folders = await this.loadFolders();
 		const meetings = listMeetings(documents, {
 			cacheData,
+			foldersByDocumentId: this.buildFoldersByDocumentId(folders),
 			limit: documents.length || 1,
 			sort: "updated-desc"
 		});
@@ -3047,6 +3272,54 @@ var GranolaApp = class {
 		this.applyAuthState(runtime.auth);
 		return this.#granolaClient;
 	}
+	buildFoldersByDocumentId(folders) {
+		if (!folders || folders.length === 0) return;
+		const byDocumentId = /* @__PURE__ */ new Map();
+		for (const folder of folders) {
+			const summary = buildFolderSummary(folder);
+			for (const documentId of folder.documentIds) {
+				const existing = byDocumentId.get(documentId) ?? [];
+				existing.push(summary);
+				byDocumentId.set(documentId, existing);
+			}
+		}
+		for (const [documentId, summaries] of byDocumentId.entries()) byDocumentId.set(documentId, summaries.slice().sort((left, right) => left.name.localeCompare(right.name)).map((folder) => cloneFolderSummary(folder)));
+		return byDocumentId;
+	}
+	async loadFolders(options = {}) {
+		if (options.forceRefresh) {
+			this.resetRemoteState();
+			this.emitStateUpdate();
+		}
+		if (this.#folders) return this.#folders.map((folder) => ({
+			...folder,
+			documentIds: [...folder.documentIds]
+		}));
+		const client = await this.getGranolaClient();
+		if (!client.listFolders) {
+			if (options.required) throw new Error("Granola folder API is not configured");
+			return;
+		}
+		try {
+			this.#folders = (await client.listFolders({ timeoutMs: this.config.notes.timeoutMs })).map((folder) => ({
+				...folder,
+				documentIds: [...folder.documentIds]
+			}));
+			this.#state.folders = {
+				count: this.#folders.length,
+				loaded: true,
+				loadedAt: this.nowIso()
+			};
+			this.emitStateUpdate();
+			return this.#folders.map((folder) => ({
+				...folder,
+				documentIds: [...folder.documentIds]
+			}));
+		} catch (error) {
+			if (options.required) throw error;
+			return;
+		}
+	}
 	missingCacheError() {
 		return /* @__PURE__ */ new Error(`Granola cache file not found. Pass --cache or create .granola.toml. Expected locations include: ${granolaCacheCandidates().join(", ")}`);
 	}
@@ -3159,12 +3432,7 @@ var GranolaApp = class {
 	}
 	async listDocuments(options = {}) {
 		if (options.forceRefresh) {
-			this.#granolaClient = void 0;
-			this.#documents = void 0;
-			this.#state.documents = {
-				count: 0,
-				loaded: false
-			};
+			this.resetRemoteState();
 			this.emitStateUpdate();
 		}
 		if (this.#documents) return this.#documents;
@@ -3205,16 +3473,57 @@ var GranolaApp = class {
 		if (options.required && !cacheData) throw this.missingCacheError();
 		return cacheData;
 	}
+	async listFolders(options = {}) {
+		const summaries = filterFolders((await this.loadFolders({
+			forceRefresh: options.forceRefresh,
+			required: true
+		}) ?? []).map((folder) => buildFolderSummary(folder)), {
+			limit: options.limit,
+			search: options.search
+		});
+		this.setUiState({
+			folderSearch: options.search,
+			selectedFolderId: void 0,
+			view: "folder-list"
+		});
+		return { folders: summaries };
+	}
+	async getFolder(id) {
+		const folders = await this.loadFolders({ required: true });
+		const cacheData = await this.loadCache();
+		const documents = await this.listDocuments();
+		const folder = resolveFolder((folders ?? []).map((folder) => buildFolderSummary(folder)), id);
+		const rawFolder = (folders ?? []).find((candidate) => candidate.id === folder.id);
+		if (!rawFolder) throw new Error(`folder not found: ${id}`);
+		const record = buildFolderRecord(rawFolder, listMeetings(documents, {
+			cacheData,
+			folderId: folder.id,
+			foldersByDocumentId: this.buildFoldersByDocumentId(folders),
+			limit: Math.max(rawFolder.documentIds.length, 1),
+			sort: "updated-desc"
+		}));
+		this.setUiState({
+			selectedFolderId: folder.id,
+			view: "folder-detail"
+		});
+		return record;
+	}
+	async findFolder(query) {
+		const summary = resolveFolderQuery((await this.loadFolders({ required: true }) ?? []).map((folder) => buildFolderSummary(folder)), query);
+		return await this.getFolder(summary.id);
+	}
 	async listMeetings(options = {}) {
 		const preferIndex = options.preferIndex ?? (this.#state.ui.surface === "web" || this.#state.ui.surface === "server");
 		if (!options.forceRefresh && preferIndex && !this.#documents && this.#meetingIndex.length > 0) {
 			const meetings = filterMeetingSummaries(this.#meetingIndex, options);
 			this.setUiState({
+				folderSearch: void 0,
 				meetingListSource: "index",
 				meetingSearch: options.search,
 				meetingSort: options.sort,
 				meetingUpdatedFrom: options.updatedFrom,
 				meetingUpdatedTo: options.updatedTo,
+				selectedFolderId: options.folderId,
 				selectedMeetingId: void 0,
 				view: "meeting-list"
 			});
@@ -3226,8 +3535,14 @@ var GranolaApp = class {
 		}
 		const cacheData = await this.loadCache();
 		const documents = await this.listDocuments({ forceRefresh: options.forceRefresh });
+		const folders = await this.loadFolders({
+			forceRefresh: options.forceRefresh,
+			required: Boolean(options.folderId)
+		});
 		const meetings = listMeetings(documents, {
 			cacheData,
+			folderId: options.folderId,
+			foldersByDocumentId: this.buildFoldersByDocumentId(folders),
 			limit: options.limit,
 			search: options.search,
 			sort: options.sort,
@@ -3236,15 +3551,18 @@ var GranolaApp = class {
 		});
 		await this.persistMeetingIndex(listMeetings(documents, {
 			cacheData,
+			foldersByDocumentId: this.buildFoldersByDocumentId(folders),
 			limit: Math.max(documents.length, 1),
 			sort: "updated-desc"
 		}));
 		this.setUiState({
+			folderSearch: void 0,
 			meetingListSource: "live",
 			meetingSearch: options.search,
 			meetingSort: options.sort,
 			meetingUpdatedFrom: options.updatedFrom,
 			meetingUpdatedTo: options.updatedTo,
+			selectedFolderId: options.folderId,
 			selectedMeetingId: void 0,
 			view: "meeting-list"
 		});
@@ -3256,9 +3574,11 @@ var GranolaApp = class {
 	async getMeeting(id, options = {}) {
 		const documents = await this.listDocuments();
 		const cacheData = await this.loadCache({ required: options.requireCache });
+		const folders = await this.loadFolders();
 		const document = resolveMeeting(documents, id);
-		const meeting = buildMeetingRecord(document, cacheData);
+		const meeting = buildMeetingRecord(document, cacheData, this.buildFoldersByDocumentId(folders)?.get(document.id));
 		this.setUiState({
+			selectedFolderId: meeting.meeting.folders[0]?.id,
 			selectedMeetingId: document.id,
 			view: "meeting-detail"
 		});
@@ -3271,9 +3591,11 @@ var GranolaApp = class {
 	async findMeeting(query, options = {}) {
 		const documents = await this.listDocuments();
 		const cacheData = await this.loadCache({ required: options.requireCache });
+		const folders = await this.loadFolders();
 		const document = resolveMeetingQuery(documents, query);
-		const meeting = buildMeetingRecord(document, cacheData);
+		const meeting = buildMeetingRecord(document, cacheData, this.buildFoldersByDocumentId(folders)?.get(document.id));
 		this.setUiState({
+			selectedFolderId: meeting.meeting.folders[0]?.id,
 			selectedMeetingId: document.id,
 			view: "meeting-detail"
 		});
@@ -3670,7 +3992,7 @@ function resolveListFormat$1(value) {
 		default: throw new Error("invalid exports format: expected text, json, or yaml");
 	}
 }
-function parseLimit$1(value) {
+function parseLimit$2(value) {
 	if (value === void 0) return 20;
 	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid exports limit: expected a positive integer");
 	const limit = Number(value);
@@ -3699,7 +4021,7 @@ const exportsCommand = {
 	async run({ commandArgs, commandFlags, globalFlags }) {
 		const [action, id] = commandArgs;
 		switch (action) {
-			case "list": return await list$1(commandFlags, globalFlags);
+			case "list": return await list$2(commandFlags, globalFlags);
 			case "rerun":
 				if (!id) throw new Error("exports rerun requires a job id");
 				return await rerun(id, commandFlags, globalFlags);
@@ -3710,9 +4032,9 @@ const exportsCommand = {
 		}
 	}
 };
-async function list$1(commandFlags, globalFlags) {
+async function list$2(commandFlags, globalFlags) {
 	const format = resolveListFormat$1(commandFlags.format);
-	const limit = parseLimit$1(commandFlags.limit);
+	const limit = parseLimit$2(commandFlags.limit);
 	const config = await loadConfig({
 		globalFlags,
 		subcommandFlags: commandFlags
@@ -3739,6 +4061,110 @@ async function rerun(id, commandFlags, globalFlags) {
 	return 0;
 }
 //#endregion
+//#region src/commands/folder.ts
+function folderHelp() {
+	return `Granola folder
+
+Usage:
+  granola folder <list|view> [options]
+
+Subcommands:
+  list                List folders from the Granola API
+  view <id|name>      Show one folder and its meetings
+
+Options:
+  --format <value>    text, json, yaml
+  --limit <n>         Number of folders for list (default: 20)
+  --search <query>    Filter folders by id, name, or description
+  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>   Path to supabase.json
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+function resolveFolderListFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid folder format: expected text, json, or yaml");
+	}
+}
+function resolveFolderDetailFormat(value) {
+	return resolveFolderListFormat(value);
+}
+function parseLimit$1(value) {
+	if (value === void 0) return 20;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid folder limit: expected a positive integer");
+	const limit = Number(value);
+	if (!Number.isInteger(limit) || limit < 1) throw new Error("invalid folder limit: expected a positive integer");
+	return limit;
+}
+const folderCommand = {
+	description: "Inspect Granola folders and their meetings",
+	flags: {
+		format: { type: "string" },
+		help: { type: "boolean" },
+		limit: { type: "string" },
+		search: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: folderHelp,
+	name: "folder",
+	async run({ commandArgs, commandFlags, globalFlags }) {
+		const [action, query] = commandArgs;
+		switch (action) {
+			case "list": return await list$1(commandFlags, globalFlags);
+			case "view":
+				if (!query) throw new Error("folder view requires an id or name");
+				return await view$1(query, commandFlags, globalFlags);
+			case void 0:
+				console.log(folderHelp());
+				return 1;
+			default: throw new Error("invalid folder command: expected list or view");
+		}
+	}
+};
+async function list$1(commandFlags, globalFlags) {
+	const format = resolveFolderListFormat(commandFlags.format);
+	const limit = parseLimit$1(commandFlags.limit);
+	const search = typeof commandFlags.search === "string" ? commandFlags.search : void 0;
+	const config = await loadConfig({
+		globalFlags,
+		subcommandFlags: commandFlags
+	});
+	debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+	debug(config.debug, "supabase", config.supabase);
+	debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+	const app = await createGranolaApp(config);
+	debug(config.debug, "authMode", app.getState().auth.mode);
+	console.log("Loading folders...");
+	const result = await app.listFolders({
+		limit,
+		search
+	});
+	console.log(renderFolderList(result.folders, format).trimEnd());
+	return 0;
+}
+async function view$1(query, commandFlags, globalFlags) {
+	const format = resolveFolderDetailFormat(commandFlags.format);
+	const config = await loadConfig({
+		globalFlags,
+		subcommandFlags: commandFlags
+	});
+	debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+	debug(config.debug, "supabase", config.supabase);
+	debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+	const app = await createGranolaApp(config);
+	debug(config.debug, "authMode", app.getState().auth.mode);
+	console.log("Fetching folder from Granola API...");
+	const result = await app.findFolder(query);
+	console.log(renderFolderView(result, format).trimEnd());
+	return 0;
+}
+//#endregion
 //#region src/browser.ts
 const execFileAsync = promisify(execFile);
 function getBrowserOpenCommand(url, platform = process.platform) {
@@ -5430,6 +5856,7 @@ async function startGranolaServer(app, options = {}) {
 			auth: true,
 			events: true,
 			exports: true,
+			folders: true,
 			meetingOpen: true,
 			webClient: enableWebClient
 		},
@@ -5439,7 +5866,7 @@ async function startGranolaServer(app, options = {}) {
 			sessionStore: defaultGranolaToolkitPersistenceLayout().sessionStoreKind
 		},
 		product: "granola-toolkit",
-		protocolVersion: 1,
+		protocolVersion: 2,
 		transport: "local-http"
 	};
 	const server = createServer(async (request, response) => {
@@ -5561,6 +5988,7 @@ async function startGranolaServer(app, options = {}) {
 				return;
 			}
 			if (method === "GET" && path === granolaTransportPaths.meetings) {
+				const folderId = url.searchParams.get("folderId")?.trim() || void 0;
 				const limit = parseInteger(url.searchParams.get("limit"));
 				const refresh = url.searchParams.get("refresh") === "true";
 				const search = url.searchParams.get("search")?.trim() || void 0;
@@ -5568,6 +5996,7 @@ async function startGranolaServer(app, options = {}) {
 				const updatedFrom = url.searchParams.get("updatedFrom")?.trim() || void 0;
 				const updatedTo = url.searchParams.get("updatedTo")?.trim() || void 0;
 				const result = await app.listMeetings({
+					folderId,
 					forceRefresh: refresh,
 					limit,
 					search,
@@ -5576,6 +6005,7 @@ async function startGranolaServer(app, options = {}) {
 					updatedTo
 				});
 				sendJson(response, {
+					folderId,
 					meetings: result.meetings,
 					refresh,
 					search,
@@ -5586,12 +6016,39 @@ async function startGranolaServer(app, options = {}) {
 				}, { headers: originHeaders });
 				return;
 			}
+			if (method === "GET" && path === granolaTransportPaths.folders) {
+				const limit = parseInteger(url.searchParams.get("limit"));
+				const refresh = url.searchParams.get("refresh") === "true";
+				const search = url.searchParams.get("search")?.trim() || void 0;
+				sendJson(response, {
+					folders: (await app.listFolders({
+						forceRefresh: refresh,
+						limit,
+						search
+					})).folders,
+					refresh,
+					search
+				}, { headers: originHeaders });
+				return;
+			}
+			if (method === "GET" && path === granolaTransportPaths.folderResolve) {
+				const query = url.searchParams.get("q")?.trim();
+				if (!query) throw new Error("folder query is required");
+				sendJson(response, await app.findFolder(query), { headers: originHeaders });
+				return;
+			}
 			if (method === "GET" && path === granolaTransportPaths.meetingResolve) {
 				const query = url.searchParams.get("q")?.trim();
 				if (!query) throw new Error("meeting query is required");
 				sendJson(response, await app.findMeeting(query, { requireCache: url.searchParams.get("includeTranscript") === "true" }), { headers: originHeaders });
 				return;
 			}
+			if (method === "GET" && path.startsWith(`${granolaTransportPaths.folders}/`) && path !== granolaTransportPaths.folderResolve) {
+				const id = decodeURIComponent(path.slice(`${granolaTransportPaths.folders}/`.length));
+				if (!id) throw new Error("folder id is required");
+				sendJson(response, await app.getFolder(id), { headers: originHeaders });
+				return;
+			}
 			if (method === "GET" && path.startsWith(`${granolaTransportPaths.meetings}/`) && path !== granolaTransportPaths.meetingResolve) {
 				const id = decodeURIComponent(path.slice(`${granolaTransportPaths.meetings}/`.length));
 				if (!id) throw new Error("meeting id is required");
@@ -5776,6 +6233,7 @@ Subcommands:
 
 Options:
   --cache <path>      Path to Granola cache JSON for transcript data
+  --folder <query>    Filter list to one folder id or name
   --format <value>    list/view: text, json, yaml; export: json, yaml; notes: markdown, json, yaml, raw; transcript: text, json, yaml, raw
   --network <mode>    open: local or lan (default: local)
   --hostname <value>  open: hostname to bind (overrides network default)
@@ -5849,6 +6307,7 @@ const meetingCommand = {
 	description: "Inspect and export individual Granola meetings",
 	flags: {
 		cache: { type: "string" },
+		folder: { type: "string" },
 		format: { type: "string" },
 		help: { type: "boolean" },
 		hostname: { type: "string" },
@@ -5892,6 +6351,7 @@ const meetingCommand = {
 async function list(commandFlags, globalFlags) {
 	const format = resolveListFormat(commandFlags.format);
 	const limit = parseLimit(commandFlags.limit);
+	const folderQuery = typeof commandFlags.folder === "string" ? commandFlags.folder : void 0;
 	const search = typeof commandFlags.search === "string" ? commandFlags.search : void 0;
 	const config = await loadConfig({
 		globalFlags,
@@ -5904,11 +6364,15 @@ async function list(commandFlags, globalFlags) {
 	const app = await createGranolaApp(config);
 	debug(config.debug, "authMode", app.getState().auth.mode);
 	console.log("Loading meetings...");
+	const folder = folderQuery ? await app.findFolder(folderQuery) : void 0;
+	const folderId = folder?.id;
 	const result = await app.listMeetings({
+		folderId,
 		limit,
 		search
 	});
 	console.log(result.source === "index" ? "Loaded meetings from the local index" : "Fetched meetings from Granola API");
+	if (folder) console.log(`Folder: ${folder.name} (${folder.id})`);
 	console.log(renderMeetingList(result.meetings, format).trimEnd());
 	return 0;
 }
@@ -6271,6 +6735,7 @@ const commands = [
 	attachCommand,
 	authCommand,
 	exportsCommand,
+	folderCommand,
 	meetingCommand,
 	notesCommand,
 	serveCommand,
@@ -6399,6 +6864,7 @@ Global options:
 
 Examples:
   granola attach http://127.0.0.1:4123
+  granola folder list
   granola notes --supabase "${granolaSupabaseCandidates()[0] ?? "/path/to/supabase.json"}"
   granola transcripts --cache "${granolaCacheCandidates()[0] ?? "/path/to/cache-v3.json"}"
 `;

package/package.json

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