New Client Setup Guide - MeetingOS (Consultant-Facing)

Step 1 · ~15 min

Create the Client's Zoom Server-to-Server OAuth App

MeetingOS fetches transcripts through the Zoom API using a Server-to-Server OAuth app on the client's Zoom account. JWT apps are deprecated - never use them. There is no per-user OAuth flow, no redirect URIs, no refresh tokens.

1. Have the client sign in at marketplace.zoom.us (they must be an account admin).
2. Develop → Build App → Server-to-Server OAuth → Create. Name it MeetingOS Transcript Fetch.
3. Copy the three credentials from the Information page: Account ID, Client ID, Client Secret.
4. On the Scopes page, add exactly these five:
   • meeting:read:meeting:admin
   • meeting:read:list_meetings:admin
   • meeting:read:past_meeting:admin - required for the instances call under granular scopes
   • user:read:user:admin
   • user:read:list_users:admin
5. Activate the app. A non-activated app is the most common day-one failure.

• App created on the client's own Zoom account (not yours)
• Five scopes added, app activated
• Three credentials copied into your password manager, labeled with the client name

Step 2 · ~5 min

Turn On Zoom AI Companion Transcript Retention

Zoom has two completely separate transcript systems, and querying the wrong one silently returns empty results. MeetingOS uses AI Companion transcripts - they do not require cloud recording, which is why they work for clients who record locally or not at all.

1. In the client's Zoom web portal (zoom.us), as admin: Settings → AI Companion.
2. Turn ON "Allow meeting hosts to retain and access meeting transcripts."
3. Recommended: Meeting Summary → "Automatically start" so transcripts generate without the host remembering anything.

Step 3 · ~10 min

Build the Client Folder - the Digital Employee's Brain

The folder is the memory. No database, no embeddings. One folder per client, and the agent's allow-list opens only that folder - that is the scope guard between clients. Structure:

CLAUDE.md is the standard briefing: company context, who attends which recurring meeting, which note style each meeting series gets, and where notes are delivered. last-check.json is what separates a real employee from a goldfish - without it the agent cannot tell a new transcript from one it already processed, and it has no record of its own previous actions.

• Client folder created from the MeetingOS master template
• .env filled in, chmod 600, confirmed outside any committed tree
• CLAUDE.md written with the client's real meeting series and people

Step 4 · ~10 min

First Transcript Test Run + Dedup Verification

From the client folder, run the fetch script once, manually, verbose:

Then run the identical command a second time. It must print All caught up. - that proves dedup state is being written to state/.fetched_instances.json and no client ever gets the same notes twice.

• GET /users/me with the token returns the user profile (OAuth works)
• First verbose run exits 0 with a status line
• Second run prints "All caught up" (dedup confirmed)

Step 5 · ~10 min

Schedule the Transcript Fetch

Schedule runs for shortly after each recurring call ends. The script retries every 5 minutes for up to ~40 minutes while Zoom processes, so it tolerates meetings that run long - and a meeting still in progress at job time is handled by polling inside that wait window, not by exiting. Example crontab for a client with Mon 1:00 PM, Wed 11:00 AM, Thu 1:00 PM calls:

launchd (macOS LaunchAgent with StartCalendarInterval) or an agent-runtime scheduler both work - the script prints only when it fetches or hits a real error, so silent runs are safe. Set TZ_NAME (e.g. America/Los_Angeles) so the lookback window and filenames match the client's meeting times.

Tuning knobs: ZOOM_TRANSCRIPT_DIR, ZOOM_STATE_FILE, ZOOM_LOOKBACK_DAYS (default 3), ZOOM_MAX_WAIT_MINUTES (default 40), --once for manual runs.

Step 6 · ~15 min

Meeting Note Formatting Rules + Delivery Destinations

The .vtt is raw material. The agent reads it (strip timestamps; speaker labels are the Name: prefix), applies a note style, and delivers. Long transcripts may need chunking at roughly 15k words per pass - extract per chunk, merge sections.

Delivery destinations (configure per client in config.yaml):

• Email - the morning brief. Always on. Recipients and send-time are client variables.
• Dashboard - the client folder's dashboard/index.html, updated after every meeting.
• Google Docs (optional) - created via the Drive API and formatted; a plain-text Google Doc is a failed delivery. One folder per meeting series.
• Notion (optional) - one database for all notes, properties for date, topic, style.
• Local markdown - the zero-config default: notes/YYYY-MM-DD_<topic>_<style>.md.

Standing formatting rules: name every file and page with date + topic + style so they sort chronologically, and every note links back to its source .vtt path so it is auditable against the raw transcript.