granola-toolkit 0.29.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.
@@ -208,12 +231,17 @@ The machine-readable `export` command includes:
 The initial server API includes:
 
 - `GET /health`
+- `GET /server/info`
 - `POST /auth/unlock` for password-protected servers
 - `POST /auth/lock` to clear the browser/API unlock cookie
 - `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`
@@ -272,6 +300,16 @@ Use it when you want:
 
 The attach flow uses the existing local HTTP API plus `GET /events` for live state updates.
 
+### Runtime Boundaries
+
+The toolkit now keeps its local persistence and transport contracts explicit:
+
+- one shared local data directory for export jobs, meeting index data, and any file-backed session state
+- one versioned local HTTP transport contract, exposed by `GET /server/info`
+- one remote client handshake that validates the transport protocol before attaching
+
+That keeps the current single-package repo simple, while making a future split into separate server/client packages or remote-hosted clients much less invasive.
+
 ### TUI
 
 `tui` starts a full-screen terminal workspace on the shared app core, without requiring the local server or browser client. Use `attach` when you want the same workspace against an existing shared server instance instead.