bloby-bot 0.50.1 → 0.50.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.50.1",
+  "version": "0.50.2",
   "releaseNotes": [
     "1. Something great..",
     "2. ",

package/supervisor/index.ts

@@ -392,6 +392,7 @@ export async function startSupervisor() {
     'POST /api/channels/whatsapp/react',
     'POST /api/channels/send',
     'POST /api/channels/alexa/handle',
+    'POST /api/whisper/transcribe-file',
   ];
 
   function isExemptRoute(method: string, url: string): boolean {

package/workspace/skills/plaud/SKILL.md

@@ -4,11 +4,11 @@
 
 A channel for getting **recordings off the user's Plaud Note device** and into your workspace as `(audio file, transcript)` pairs you can read and act on.
 
-Plaud is a tiny voice recorder (button on the case, magnet sticks to a phone). When the user records something — a meeting, a lecture, a thought on a walk — the device syncs to Plaud's cloud over Bluetooth/Wi-Fi. **You don't talk to the device.** You talk to Plaud's cloud, pull the audio, and transcribe it yourself.
+Plaud is a tiny voice recorder. When the user records something — a meeting, a lecture, a thought on a walk — the device syncs to Plaud's cloud over Bluetooth/Wi-Fi. **You don't talk to the device.** You talk to Plaud's cloud, pull the audio, and transcribe it yourself.
 
 There is **no Plaud CLI, no Plaud webhook, no official Plaud API.** Plaud's mobile/web app uses an undocumented HTTP API. This skill uses the same one — same shape OpenPlaud uses (`https://github.com/openplaud/openplaud`).
 
-The user already pays Plaud $0 if they don't want Plaud's transcription subscription. We do transcription locally via Whisper using the OpenAI key the user added during the Bloby wizard. No new key, no new subscription.
+The user already has Whisper enabled via the Bloby wizard. We use that OpenAI key — no new key, no new subscription, no Plaud AI plan needed.
 
 ---
 
@@ -16,18 +16,36 @@ The user already pays Plaud $0 if they don't want Plaud's transcription subscrip
 
 | Thing | Where | How you use it |
 |---|---|---|
-| Whisper-on-disk endpoint | `POST http://localhost:7400/api/whisper/transcribe-file` | Send a path under `workspace/files/`, get a transcript back. Optional `saveTranscriptNext: true` writes `foo.mp3.txt` next to `foo.mp3`. |
-| Settings k/v store | `GET/POST/PUT http://localhost:7400/api/settings` | Store/retrieve the Plaud JWT, region, workspace ID, last-sync cursor. |
-| Workspace files dir | `workspace/files/audio/plaud/` | Drop downloaded audio here. The supervisor serves it at `/api/files/audio/plaud/<name>`. |
+| Whisper-on-disk endpoint | `POST http://localhost:7400/api/whisper/transcribe-file` | Send a path under `workspace/files/`, get a transcript back. Optional `saveTranscriptNext: true` writes `foo.mp3.txt` next to `foo.mp3`. Auth-exempt, no Bearer needed. |
+| Workspace files dir | `workspace/files/audio/plaud/` | Drop downloaded audio here. Supervisor serves it at `/api/files/audio/plaud/<name>`. |
+| Workspace file tools | `Read` / `Write` / `Edit` | Store Plaud auth state in `workspace/.plaud.json` (see below). No `/api/settings` calls — that endpoint requires a portal Bearer token the skill can't easily produce. |
 | Scheduling | `workspace/CRONS.json` or `workspace/PULSE.json` | Run sync periodically. See "Cadence" below. |
 
-Use `http://localhost:7400` from Bash. Auth is the same Bearer token you already have in your session for the worker; for skill-internal calls running inside the supervisor's own bloby session, `/api/settings` and `/api/whisper/transcribe-file` work the same way `/api/whisper/transcribe` does.
+Use `http://localhost:7400` from Bash for the Whisper endpoint. Everything else is the open internet (Plaud's API) or your own filesystem.
+
+### State file: `workspace/.plaud.json`
+
+You manage all Plaud connection state in a single JSON file at workspace root. Read with `Read`, write with `Write`. Shape:
+
+```json
+{
+  "email": "bruno@bertapeli.com",
+  "apiBase": "https://api.plaud.ai",
+  "userToken": "eyJ...",
+  "workspaceId": "ws_xxxxx",
+  "workspaceToken": "eyJ...",
+  "workspaceTokenMintedAt": "2026-05-22T19:30:00.000Z",
+  "lastSyncVersionMs": 1716412800000
+}
+```
+
+Initialize empty (`{}`) if the file doesn't exist. Never commit secrets — `.plaud.json` is gitignored by default (starts with `.`).
 
 ---
 
 ## Plaud's API in 60 seconds
 
-Three regions. Pick one when pairing. Token from one region won't work on another.
+Three regions. Pick one when pairing. A token from one region won't work on another.
 
 | Region | Base URL |
 |---|---|
@@ -35,9 +53,16 @@ Three regions. Pick one when pairing. Token from one region won't work on anothe
 | EU | `https://api-euc1.plaud.ai` |
 | Asia-Pacific | `https://api-apse1.plaud.ai` |
 
-If the user doesn't know their region, start with Global. If `POST /auth/otp-send-code` returns `status: -302` with `data.domains.api`, redirect to that base instead — the user's account lives in a different region. Save whichever base actually succeeded.
+If the user doesn't know their region, start with Global. If `POST /auth/otp-send-code` returns `status: -302` with `data.domains.api`, retry against that base — the user's account lives in a different region. Save whichever base actually succeeded.
 
-**User-Agent matters.** Plaud blocks some defaults. Always send a normal browser UA. Example:
+**Two token kinds.** This is the part that bites everyone:
+
+- **User Token (UT)** — what `/auth/otp-login` returns. Authenticates `/user/me`, the workspace-list endpoint, and the workspace-token mint endpoint. **It does NOT authenticate recording endpoints.** Calling `/file/simple/web` or `/device/list` with a UT silently returns HTTP 200 + empty list. This is exactly the "I have no recordings but my Plaud app shows 3 files" symptom.
+- **Workspace Token (WT)** — minted from the UT. Required on all recording endpoints. ~24h lifetime. Re-mint when expired.
+
+**You always need both.** UT lives long, WT is short-lived. Workflow: OTP → UT → list workspaces (with UT) → mint WT for the personal workspace (with UT) → use WT for everything recording-related.
+
+**User-Agent matters.** Plaud blocks some defaults. Always send a normal browser UA:
 
 ```
 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
@@ -56,7 +81,7 @@ Bloby: Which email do you use on plaud.ai? I'll have them send you a 6-digit cod
 Human: bruno@example.com
 ```
 
-If the human mentions they signed up with **Google or Apple**, jump to the "Paste-token fallback" section instead. OTP only works for accounts that were created with an email+password identity on Plaud's side.
+If the human mentions they signed up with **Google or Apple**, jump to the "Paste-token fallback" section — OTP only works for email+password Plaud identities.
 
 ### Step 2 — Send the OTP
 
@@ -84,34 +109,81 @@ curl -s -X POST '<apiBase>/auth/otp-login' \
   -d '{"code":"<6 DIGITS>","token":"<OTP TOKEN FROM STEP 2>"}'
 ```
 
-Expected `access_token` (a long `eyJ...` JWT). **This is the long-lived token. Store it.**
+Expected `access_token` (a long `eyJ...` JWT). **This is the User Token (UT). Save it as `userToken`.**
+
+> ⚠️ **Don't be misled by `is_new_user: true`** in this response. It's an informational flag for the Plaud client — it does NOT mean Plaud just created a fresh account for you. Your real account is intact. The empty `data_devices: []` you'll see next is because UT can't read recording/device endpoints — that's the workspace-token issue, not "wrong account."
 
-### Step 5 — Store the connection
+### Step 5 — Write initial state to `workspace/.plaud.json`
+
+Use the `Write` tool. No `/api/settings` calls.
+
+```json
+{
+  "email": "<EMAIL>",
+  "apiBase": "<BASE THAT WORKED>",
+  "userToken": "<UT FROM STEP 4>"
+}
+```
+
+### Step 6 — Smoke test the UT (don't try `/device/list` yet)
 
 ```bash
-# Each setting saved separately. Replace <TOKEN> and <BASE>.
-curl -s -X POST 'http://localhost:7400/api/settings' \
-  -H 'Content-Type: application/json' \
-  -d '{"key":"plaud_token","value":"<JWT>"}'
-curl -s -X POST 'http://localhost:7400/api/settings' \
-  -H 'Content-Type: application/json' \
-  -d '{"key":"plaud_api_base","value":"<BASE>"}'
-curl -s -X POST 'http://localhost:7400/api/settings' \
+curl -s '<BASE>/user/me' \
+  -H 'Authorization: Bearer <UT>' \
+  -H 'User-Agent: Mozilla/5.0 ...'
+```
+
+Should return the user's profile (email matches the one you used to pair). If 401, the UT is bad — start over. If 200 but the email is different from what the human gave you, the OTP went to a different identity (Google/Apple collision) — explain and go to paste-token fallback.
+
+### Step 7 — Mint the Workspace Token (REQUIRED)
+
+This is the step that makes the difference between "0 recordings" and "all 3 of my recordings."
+
+**7a. List workspaces** (auth: UT):
+
+```bash
+curl -s '<BASE>/team-app/workspaces/list?need_personal_workspace=true' \
+  -H 'Authorization: Bearer <UT>' \
+  -H 'User-Agent: Mozilla/5.0 ...'
+```
+
+Response shape: `{ status: 0, data: { workspaces: [{ workspace_id, workspace_type, ... }] } }`.
+
+Pick the **personal** workspace — the one where `workspace_type === "0"`. If no workspace has type `"0"` (rare), use the first entry. Save its `workspace_id` as `workspaceId`.
+
+**7b. Mint a WT for that workspace** (auth: UT, body is literally `{}`):
+
+```bash
+curl -s -X POST '<BASE>/user-app/auth/workspace/token/<WORKSPACE_ID>' \
+  -H 'Authorization: Bearer <UT>' \
   -H 'Content-Type: application/json' \
-  -d '{"key":"plaud_email","value":"<EMAIL>"}'
+  -H 'User-Agent: Mozilla/5.0 ...' \
+  -d '{}'
 ```
 
-You can also save `plaud_workspace_id` once you discover it (see "Workspaces" below).
+Response: `{ status: 0, data: { workspace_token: "eyJ..." } }`.
 
-### Step 6 — Smoke test
+**Save it** as `workspaceToken` and `workspaceTokenMintedAt: <now ISO 8601>` in `.plaud.json`. Now Update the file via `Write`.
+
+### Step 8 — Real smoke test (with WT)
 
 ```bash
 curl -s '<BASE>/device/list' \
-  -H 'Authorization: Bearer <JWT>' \
+  -H 'Authorization: Bearer <WT>' \
   -H 'User-Agent: Mozilla/5.0 ...'
 ```
 
-Should return a JSON object listing the user's Plaud devices (each has a `serial_number`). If you get `401`, the OTP didn't grant a usable token — start over. If `200`, tell the human: *"Paired. Your Plaud (serial ending ...XXXX) is connected. Want me to pull in everything you've recorded so far?"*
+Now you should see devices. Tell the human: *"Paired. Your Plaud (serial ending ...XXXX) is connected. Want me to pull in everything you've recorded so far?"*
+
+If `data_devices` is still empty here — odd, but possible for accounts that haven't synced any device in a while. Try the recordings list directly:
+
+```bash
+curl -s '<BASE>/file/simple/web?skip=0&limit=10&is_trash=0' \
+  -H 'Authorization: Bearer <WT>' \
+  -H 'User-Agent: Mozilla/5.0 ...'
+```
+
+If `data_file_list` has entries, you're good — devices list can be empty even when recordings exist.
 
 ---
 
@@ -123,9 +195,8 @@ If OTP just won't work and the human signed up with Google or Apple, get the bea
 2. Open DevTools (F12 or Cmd+Option+I) → Network tab → refresh.
 3. Click any request to `api.plaud.ai`, `api-euc1.plaud.ai`, or `api-apse1.plaud.ai`.
 4. Under **Request Headers**, find `Authorization`. Copy everything after `Bearer ` (the long `eyJ...`).
-5. Tell the bloby in chat. The bloby saves it via the same `plaud_token` setting key, plus the matching `plaud_api_base`.
-
-JWTs from this path expire too. The skill behaviour on 401 is the same (see "Re-auth" below).
+5. The human pastes it to you in chat. Save it as `userToken` and set `apiBase` to whichever host they pulled it from.
+6. **Still run Step 7** — mint a workspace token. The paste-token gives you a UT, same as OTP. WT is still required.
 
 ---
 
@@ -134,18 +205,22 @@ JWTs from this path expire too. The skill behaviour on 401 is the same (see "Re-
 The shape of a sync run:
 
 ```
-GET /file/simple/web      → list recent recordings (paginated)
+GET /file/simple/web      → list recent recordings (paginated)   [auth: WT]
 for each new one:
-  GET /file/temp-url/<id>?is_opus=0   → get a short-lived S3 link (request the mp3, not opus)
-  curl -o workspace/files/audio/plaud/<id>.mp3  → download
-  POST /api/whisper/transcribe-file  → produces <id>.mp3.txt alongside
+  GET /file/temp-url/<id>?is_opus=0   → get a short-lived S3 link   [auth: WT]
+  curl -o workspace/files/audio/plaud/<id>.mp3  → download (no auth, signed URL)
+  POST /api/whisper/transcribe-file              → produces <id>.mp3.txt alongside
 ```
 
-### List recordings
+### Pre-sync: check WT freshness
+
+Read `.plaud.json`. If `workspaceToken` is missing or `workspaceTokenMintedAt` is more than ~20 hours old, re-mint (Step 7b above) and update the file before starting the sync. WT lifetime is ~24h; refresh defensively.
+
+### List recordings (auth: WT)
 
 ```bash
 curl -s '<BASE>/file/simple/web?skip=0&limit=50&is_trash=0&sort_by=edit_time&is_desc=true' \
-  -H 'Authorization: Bearer <JWT>' \
+  -H 'Authorization: Bearer <WT>' \
   -H 'User-Agent: Mozilla/5.0 ...'
 ```
 
@@ -161,37 +236,37 @@ The response has `data_file_list` — an array of recording objects. Fields you'
 | `serial_number` | Which Plaud device. |
 | `is_trash` | Skip if 1. |
 
-Page with `skip=` (the API also accepts a huge `limit`, but page through 50-at-a-time politely).
+Page with `skip=`; do 50 at a time. Stop when a page comes back smaller than `limit` or empty.
 
 ### Dedup
 
 You don't want to re-download what you already have. Two ways, pick one:
 
 - **Filesystem**: if `workspace/files/audio/plaud/<id>.mp3` exists, skip it.
-- **Cursor**: save the newest `version_ms` you've seen as `plaud_last_sync` setting. On next sync, skip anything `<=` that cursor. Faster — no `ls` needed.
+- **Cursor**: save the newest `version_ms` you've seen as `lastSyncVersionMs` in `.plaud.json`. Skip anything `<=` that cursor next time.
 
 If `version_ms` changed on a recording you already downloaded, the user edited the filename or trimmed it. Re-fetch and overwrite.
 
-### Get the download URL
+### Get the download URL (auth: WT)
 
 ```bash
 curl -s '<BASE>/file/temp-url/<FILE_ID>?is_opus=0' \
-  -H 'Authorization: Bearer <JWT>' \
+  -H 'Authorization: Bearer <WT>' \
   -H 'User-Agent: Mozilla/5.0 ...'
 ```
 
-`is_opus=0` returns the mp3 variant (`temp_url`). `is_opus=1` returns opus in `temp_url_opus`. **Use mp3** — Whisper handles it cleanly, opus needs ffmpeg.
+`is_opus=0` returns mp3 in `temp_url`. `is_opus=1` returns opus in `temp_url_opus`. **Use mp3** — Whisper handles it natively, opus would need ffmpeg.
 
-Response: `{ "temp_url": "https://<s3...>" }`. The URL expires in a few minutes. Download immediately.
+The URL expires in minutes. Download immediately.
 
-### Download
+### Download (no auth — URL is signed)
 
 ```bash
 mkdir -p workspace/files/audio/plaud
 curl -s -o "workspace/files/audio/plaud/<FILE_ID>.mp3" '<TEMP URL>'
 ```
 
-### Transcribe
+### Transcribe (no auth — endpoint is exempt)
 
 ```bash
 curl -s -X POST 'http://localhost:7400/api/whisper/transcribe-file' \
@@ -199,18 +274,15 @@ curl -s -X POST 'http://localhost:7400/api/whisper/transcribe-file' \
   -d '{"path":"audio/plaud/<FILE_ID>.mp3","saveTranscriptNext":true}'
 ```
 
-Returns `{ "transcript": "...", "transcriptPath": "audio/plaud/<FILE_ID>.mp3.txt" }`. The `.txt` file is now sitting next to the audio. You can read it with `Read` like any other file.
-
-The user's `whisper_key` from the wizard is what powers this — you don't need to know or handle the OpenAI key.
+Returns `{ "transcript": "...", "transcriptPath": "audio/plaud/<FILE_ID>.mp3.txt" }`. The `.txt` file is sitting next to the audio. Read it with the `Read` tool like any other file.
 
-If transcription fails (e.g. file >25MB, Whisper API's own hard limit), leave the audio in place and skip the `.txt`. The human can ask you to split/compress later.
+If Whisper fails (file >25MB is Whisper's own hard cap; rate-limit; network), leave the audio in place and skip the `.txt`. The human can ask you to split/compress later.
 
 ### Pretty filenames (optional)
 
-Tell the human you can keep the raw `<FILE_ID>.mp3` filenames, OR you can also rename to something human-readable. If they want pretty names:
+Tell the human you can keep raw `<id>.mp3` filenames or also create human-readable copies. If they want pretty names:
 
 ```bash
-# After successful transcribe, also write a symlink or copy with a nicer name:
 NICE="$(date -d "<start_time>" +%Y-%m-%d_%H%M)_<sanitised filename>"
 ln -s "<FILE_ID>.mp3" "workspace/files/audio/plaud/${NICE}.mp3"
 ln -s "<FILE_ID>.mp3.txt" "workspace/files/audio/plaud/${NICE}.txt"
@@ -218,79 +290,70 @@ ln -s "<FILE_ID>.mp3.txt" "workspace/files/audio/plaud/${NICE}.txt"
 
 (Sanitise `filename` by stripping `/\\:*?"<>|`.)
 
-Don't rename the originals — keep `<id>.mp3` as the canonical name so dedup keeps working.
+Don't rename originals — `<id>.mp3` stays canonical so dedup keeps working.
 
 ---
 
 ## Cadence — CRON or PULSE?
 
-**There is no automatic cron set up by this skill.** You and your human decide together. Two reasonable patterns:
+**This skill installs no automatic schedule.** You and your human decide together.
 
 ### Pattern A — CRON every N minutes
 
-When the human wants near-real-time freshness ("any time I record something, you should know about it within 15 minutes"), add an entry to `workspace/CRONS.json`:
+When the human wants near-real-time freshness, add an entry to `workspace/CRONS.json`:
 
 ```json
 {
   "id": "plaud-sync",
   "schedule": "*/15 * * * *",
-  "task": "Run a Plaud sync: list new recordings, download any new ones into workspace/files/audio/plaud/, and transcribe them via /api/whisper/transcribe-file. After, summarise to the human in chat IF there were new recordings — otherwise stay silent.",
+  "task": "Run a Plaud sync per the plaud skill: refresh WT if needed, list new recordings, download into workspace/files/audio/plaud/, and transcribe via /api/whisper/transcribe-file. If new recordings were found, summarise to the human in chat. If nothing new, stay silent.",
   "enabled": true,
   "oneShot": false
 }
 ```
 
-Tune `*/15` to taste. `*/5` for aggressive, `0 * * * *` (top of every hour) for quiet.
+Tune `*/15` to taste. `*/5` for aggressive, `0 * * * *` for quiet.
 
 ### Pattern B — PULSE memo
 
-When the human prefers their bloby just *check* during normal pulse wake-ups, add one line to your `MYSELF.md` or `MEMORY.md`:
+When the human prefers their bloby just *check* during normal pulse wake-ups, add one line to `MYSELF.md` or `MEMORY.md`:
 
 ```
 - Each pulse, briefly check Plaud for new recordings via the plaud skill. If there's something new, transcribe and decide whether to surface it. If nothing new, move on silently.
 ```
 
-Pulse runs every 30 min by default. No CRON entry needed. Less aggressive than Pattern A, fits naturally with whatever else you're doing at pulse time.
+Pulse runs every 30 min by default.
 
 ### Or: don't auto-sync at all
 
-Some humans only want manual control: *"Bloby, pull anything new from Plaud."* That's also fine — just keep the skill installed, no CRON, no pulse memo, you sync when asked.
+Manual only. Keep the skill installed, no CRON, no pulse memo, sync when asked.
 
-**Always check with the human first.** Default to Pattern B for new installs unless they tell you otherwise.
+**Default to Pattern B for new installs unless the human says otherwise.**
 
 ---
 
 ## Re-auth (401 handling)
 
-When any Plaud call returns 401:
+Two different 401s, two different fixes.
+
+| Endpoint that 401'd | What expired | Fix |
+|---|---|---|
+| `/file/simple/web`, `/file/temp-url/*`, `/device/list` (auth: WT) | Workspace token expired | Re-mint a WT from the cached UT (Step 7b). Don't bother the human. |
+| `/user-app/auth/workspace/token/...`, `/team-app/workspaces/list`, `/user/me` (auth: UT) | User token expired | Tell the human, re-run OTP from Step 1. |
 
-1. Tell the human in chat: *"Your Plaud connection expired. Want me to re-pair?"* Don't silently fail.
-2. If they say yes, re-run the OTP flow from Step 1. Overwrite the `plaud_token` setting.
-3. If they signed up with Google/Apple originally, prompt for the paste-token fallback instead.
-4. Don't keep retrying with the dead token — pause the sync until re-paired.
+If you can't tell which token expired (e.g. you tried to mint a WT and got 401), assume UT is dead → re-OTP.
 
 ---
 
 ## Disconnect
 
+Delete the state file:
+
 ```bash
-curl -s -X POST 'http://localhost:7400/api/settings' \
-  -H 'Content-Type: application/json' \
-  -d '{"key":"plaud_token","value":""}'
-curl -s -X POST 'http://localhost:7400/api/settings' \
-  -H 'Content-Type: application/json' \
-  -d '{"key":"plaud_api_base","value":""}'
+rm -f workspace/.plaud.json
 ```
 
-Recordings already on disk stay. The user can also disable the CRON entry (or remove it from `CRONS.json`).
-
----
-
-## Workspaces (advanced)
-
-Plaud's "workspace" is their multi-account team feature. Personal accounts don't usually need to worry about this — the API responds correctly without a workspace token. If a human ever reports recordings missing that they can see in the Plaud app, it's likely a workspace-scoped recording.
-
-To resolve a workspace token: there's an undocumented `/workspace/...` endpoint that mints a workspace-scoped token. OpenPlaud's `src/lib/plaud/workspace.ts` is the reference if you ever need it. Don't bother unless the human hits this case.
+Recordings already on disk stay. The human can also disable the CRON entry / remove it from `CRONS.json`.
 
 ---
 
@@ -299,27 +362,32 @@ To resolve a workspace token: there's an undocumented `/workspace/...` endpoint
 - **No Plaud transcription.** We transcribe ourselves with Whisper. Plaud's own AI subscription is bypassed entirely.
 - **No dashboard.** OpenPlaud has a slick UI for browsing recordings. We don't. The bloby's job is to *read* the transcripts and act on them — summaries, action items, emails — using the normal workspace tools. If the human wants a UI, build one into `workspace/client/` as a normal workspace app.
 - **No push from Plaud.** No webhooks exist. You only know about new recordings when you ask.
-- **No editing recordings.** The Plaud API technically supports `PATCH /file/<id>` to rename. We don't expose it here — keep canonical `<id>.mp3` names.
-- **No real-time streaming.** Plaud syncs to its cloud *after* the recording finishes. Expect a lag of seconds-to-minutes between "user stopped recording" and "file appears in `/file/simple/web`."
+- **No editing recordings.** The Plaud API technically supports `PATCH /file/<id>` to rename. We don't expose it — keep canonical `<id>.mp3` names.
+- **No real-time streaming.** Plaud syncs to its cloud *after* the recording finishes. Expect seconds-to-minutes of lag between "user stopped recording" and "file appears in `/file/simple/web`."
 
 ---
 
 ## Quick Reference
 
-| Action | curl |
-|---|---|
-| Send OTP | `POST <base>/auth/otp-send-code` body `{username}` |
-| Verify OTP | `POST <base>/auth/otp-login` body `{code, token}` |
-| List devices | `GET <base>/device/list` |
-| List recordings | `GET <base>/file/simple/web?skip=0&limit=50&is_trash=0&sort_by=edit_time&is_desc=true` |
-| Get download URL | `GET <base>/file/temp-url/<id>?is_opus=0` |
-| Transcribe local file | `POST http://localhost:7400/api/whisper/transcribe-file` body `{path, saveTranscriptNext}` |
-| Save setting | `POST http://localhost:7400/api/settings` body `{key, value}` |
+| Action | curl | Auth |
+|---|---|---|
+| Send OTP | `POST <base>/auth/otp-send-code` body `{username}` | none |
+| Verify OTP → UT | `POST <base>/auth/otp-login` body `{code, token}` | none |
+| Profile | `GET <base>/user/me` | UT |
+| List workspaces | `GET <base>/team-app/workspaces/list?need_personal_workspace=true` | UT |
+| Mint WT | `POST <base>/user-app/auth/workspace/token/<workspaceId>` body `{}` | UT |
+| List devices | `GET <base>/device/list` | **WT** |
+| List recordings | `GET <base>/file/simple/web?skip=0&limit=50&is_trash=0&sort_by=edit_time&is_desc=true` | **WT** |
+| Get download URL | `GET <base>/file/temp-url/<id>?is_opus=0` | **WT** |
+| Download audio | `GET <temp_url>` | none (signed) |
+| Transcribe local file | `POST http://localhost:7400/api/whisper/transcribe-file` body `{path, saveTranscriptNext}` | none (exempt) |
+
+State file: `workspace/.plaud.json` — read/write with `Read` / `Write`. **No `/api/settings` calls** — that endpoint requires a portal Bearer token the skill can't easily produce.
 
-All Plaud requests need `Authorization: Bearer <JWT>` + a browser-style `User-Agent`.
+All Plaud requests need a browser-style `User-Agent`.
 
 ---
 
 ## Credit
 
-Plaud API shape is the same one [OpenPlaud](https://github.com/openplaud/openplaud) uses — they did the reverse-engineering work. This skill reimplements just the parts a bloby needs.
+Plaud API shape is the same one [OpenPlaud](https://github.com/openplaud/openplaud) uses — they did the reverse-engineering work, including the painful workspace-token discovery (their issue #66). This skill reimplements just the parts a bloby needs.