teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/infrastructure/config.py

@@ -0,0 +1,987 @@
+"""CLI argument parsing and configuration resolution.
+
+Replaces ``parse_args()`` and ``resolve_config()`` from the original
+``transcript_download.py``.
+
+Key design changes:
+
+* ``resolve_config()`` returns a frozen :class:`~domain.models.MeetingConfig`
+  Pydantic model instead of a plain dict.
+* No global state is mutated.  The caller constructs ``Logger`` and
+  ``ShutdownCoordinator`` from the returned config's ``quiet``, ``verbose``,
+  and ``format_json`` properties.
+* ``exit_error()`` is called with an explicit ``format_json`` parameter
+  derived from the parsed args.
+* An optional *env_override* parameter allows tests to inject environment
+  variable overrides without patching ``os.environ`` externally.
+* ``_GcpSettings`` (pydantic-settings) centralises env var names and defaults
+  for GCP and tenant configuration.
+
+Schema version: 1.1.0
+Created: 2026-04-25
+Updated: 2026-05-01 -- added _GcpSettings pydantic-settings model
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import tempfile
+from datetime import date, datetime, timezone
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from teams_transcripts.domain.models import MeetingConfig
+from teams_transcripts.infrastructure.errors import EXIT_BAD_ARGS, exit_error
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_args() -> argparse.Namespace:
+    """Define and parse command-line arguments.
+
+    Returns the parsed namespace.  This function is a direct extraction
+    of the argument definitions from the original script, preserving the
+    identical CLI contract (flags, help text, defaults, mutual exclusivity).
+    """
+    p = argparse.ArgumentParser(
+        description=(
+            "Download Microsoft Teams meeting transcripts, chat, and participant "
+            "metadata as WebVTT or structured JSON.\n"
+            "\n"
+            "Connects to the Teams desktop app via the Chrome DevTools Protocol (CDP),\n"
+            "navigates to the specified meeting, and extracts the requested\n"
+            "components.  Transcript extraction uses Recap > Transcript; chat-only\n"
+            "and metadata-only modes skip transcript download.  An LLM agent\n"
+            "(Claude via Vertex AI) assists with non-deterministic UI steps such as\n"
+            "search result selection, occurrence selection, and iframe disambiguation.\n"
+            "\n"
+            "Two transcript download approaches are supported and auto-detected:\n"
+            "  A) Native blob interception -- used when you have download permission.\n"
+            "     The script clicks the Download button and intercepts the resulting\n"
+            "     blob URL to capture the VTT content byte-for-byte.\n"
+            "  B) React fibre tree extraction -- used when download is blocked.\n"
+            "     The script walks the React component tree to extract all transcript\n"
+            "     entries directly from the in-memory data structure.\n"
+            "\n"
+            "Speaker names are resolved using the Recap Speakers tab.  Vendor-prefixed\n"
+            "names (e.g. 'v-Jane Smith (Acme)') and synthetic placeholders (e.g. '@1')\n"
+            "are replaced with clean display names (e.g. 'Jane Smith', 'Speaker 1').\n"
+            "\n"
+            "Use --list-tenants to discover available Azure AD tenants before\n"
+            "downloading.  Use --tenant to verify (and auto-switch) the active tenant."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "prerequisites:\n"
+            "  1. Microsoft Teams desktop app (macOS) must be running with CDP enabled.\n"
+            "     The script will set the required flags and relaunch Teams automatically\n"
+            "     if CDP is not responding on the configured port.  To launch manually:\n"
+            "       export WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS="
+            "'--remote-debugging-port=9333'\n"
+            "       open -a 'Microsoft Teams'\n"
+            "\n"
+            "  2. Google Cloud Application Default Credentials (ADC) must be configured\n"
+            "     for the Vertex AI project.  The simplest way:\n"
+            "       gcloud auth application-default login\n"
+            "     Or point --adc / GOOGLE_ADC at a service account key file.\n"
+            "\n"
+            "  3. Python dependencies (websockets, anthropic[vertex], mcp) are managed\n"
+            "     by uv.  Run 'uv sync' to install from the lockfile.  After setup,\n"
+            "     use ./bin/teams-transcripts (or 'uv run teams-transcripts') to run.\n"
+            "\n"
+            "environment variables (used as fallbacks when CLI flags are omitted):\n"
+            "  GOOGLE_CLOUD_PROJECT  GCP project ID for Vertex AI (required if\n"
+            "                        --gcp-project is not provided)\n"
+            "  CLOUD_ML_REGION       Vertex AI region (default: 'global')\n"
+            "  MODEL_ID              Anthropic model ID (default: 'claude-haiku-4-5')\n"
+            "  GOOGLE_ADC            Path to ADC JSON credentials file\n"
+            "  TEAMS_TENANT          Azure AD tenant domain (same as --tenant)\n"
+            "\n"
+            "examples:\n"
+            "  # Basic usage -- download a single-occurrence meeting transcript\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 \\\n"
+            "    --output ./transcripts/kickoff.vtt \\\n"
+            "    --gcp-project my-vertex-project\n"
+            "\n"
+            "  # Recurring meeting -- the script finds the correct occurrence by date\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --output ./transcripts/standup-2026-04-14.vtt\n"
+            "\n"
+            "  # Disambiguate two meetings with the same name on the same day\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14T14:00 \\\n"
+            "    --output ./transcripts/standup-afternoon.vtt\n"
+            "\n"
+            "  # Pipe VTT to stdout (no file written)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 | less\n"
+            "\n"
+            "  # JSON output to file (nothing on stdout)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 \\\n"
+            "    --output ./kickoff.json --format json\n"
+            "\n"
+            "  # Structured JSON on stdout (agent-friendly)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Project Kickoff' \\\n"
+            "    --datetime 2026-04-20 --format json\n"
+            "\n"
+            "  # Dry-run -- check meeting exists without downloading\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 --dry-run --format json\n"
+            "\n"
+            "  # Quiet mode for cron or agent use\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --output ./standup.vtt -q\n"
+            "\n"
+            "  # Verify tenant before downloading (auto-switch if needed)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --output ./standup.vtt \\\n"
+            "    --tenant abccorp.com\n"
+            "\n"
+            "  # List available tenants (no download)\n"
+            "  %(prog)s --list-tenants\n"
+            "  %(prog)s --list-tenants --format json\n"
+            "  %(prog)s --list-tenants --output tenants.json --format json\n"
+            "\n"
+            "  # List meetings with transcripts (today only)\n"
+            "  %(prog)s --list-transcripts\n"
+            "\n"
+            "  # List meetings with transcripts (last 7 days)\n"
+            "  %(prog)s --list-transcripts 7\n"
+            "\n"
+            "  # List meetings as JSON, write to file\n"
+            "  %(prog)s --list-transcripts 14 --format json --output meetings.json\n"
+            "\n"
+            "  # Download by meeting ID (UUID from --list-transcripts output)\n"
+            "  %(prog)s \\\n"
+            "    --meeting-id 2b4c1f5c-636d-4d78-a087-c2cbf3887fd8 \\\n"
+            "    --output ./transcripts/meeting.vtt\n"
+            "\n"
+            "  # Use a specific model and region\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Quarterly Review' \\\n"
+            "    --datetime 2026-03-31 \\\n"
+            "    --output ./review.vtt \\\n"
+            "    --model claude-sonnet-4-20250514 \\\n"
+            "    --gcp-region us-east5\n"
+            "\n"
+            "  # Extract only chat messages (faster, no transcript download)\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --transcript no --metadata no --format json\n"
+            "\n"
+            "  # Extract only participant metadata\n"
+            "  %(prog)s \\\n"
+            "    --meeting 'Weekly Standup' \\\n"
+            "    --datetime 2026-04-14 \\\n"
+            "    --transcript no --chat no --format json\n"
+            "\n"
+            "argument constraints:\n"
+            "  --meeting and --meeting-id are mutually exclusive.\n"
+            "  --datetime is ONLY valid with --meeting.  It is incompatible with\n"
+            "  --meeting-id (the meeting date is resolved automatically from the UUID).\n"
+            "  --list-tenants and --list-transcripts are incompatible with --meeting,\n"
+            "  --meeting-id, --datetime, --dry-run, --transcript, --chat, --metadata.\n"
+            "  --dry-run and --output are incompatible.\n"
+            "  --format vtt and --list-transcripts are incompatible.\n"
+            "  --format vtt and --transcript no are incompatible (when explicitly set).\n"
+            "  At least one of --transcript, --chat, or --metadata must be yes,\n"
+            "  except with --dry-run for a pure meeting-exists check.\n"
+            "  --quiet and --verbose are mutually exclusive.\n"
+            "\n"
+            "how it works:\n"
+            "  Step 1  Verify Teams is running with CDP enabled (relaunch if needed)\n"
+            "  Step 2  Confirm CDP is responding on the configured port\n"
+            "  Step 3  Discover Teams page targets via CDP\n"
+            "  Step 3b Verify tenant (when --tenant specified; switch if needed)\n"
+            "  Step 3c Resolve meeting UUID to subject and date (when --meeting-id\n"
+            "          is used instead of --meeting)\n"
+            "  Step 4  Search for the meeting by name and navigate to its chat\n"
+            "  Step 5  Open Recap when needed, select the correct date occurrence,\n"
+            "          extract speaker names, then switch to the Transcript tab\n"
+            "          only when transcript output is requested\n"
+            "  Step 6  Locate the transcript iframe target when transcript output\n"
+            "          is requested\n"
+            "  Step 7  Download the transcript (Approach A or B, auto-detected)\n"
+            "          when requested; extract roster members and output chat\n"
+            "          messages when requested; read Event/Call messages and RSVP\n"
+            "          tracking when needed for metadata; then build VTT or\n"
+            "          structured JSON\n"
+            "  Step 8  Validate generated transcript content when transcript output\n"
+            "          is requested\n"
+            "\n"
+            "notes:\n"
+            "  - The meeting name must match what appears in Teams search results.\n"
+            "    Partial matches work as long as the name is unambiguous.\n"
+            "  - For recurring meetings, the occurrence dropdown must contain the\n"
+            "    target date.  Teams typically retains the most recent ~5 occurrences.\n"
+            "    Older occurrences may no longer be available.\n"
+            "  - The script retries up to 4 times with different search results if\n"
+            "    the first result does not contain the target date.\n"
+            "  - Output file is overwritten if it already exists.\n"
+            "  - All diagnostic output goes to stderr.  stdout carries only data\n"
+            "    (VTT content, or JSON when --format json is set).\n"
+            "  - In JSON mode with --output, the structured JSON is written to\n"
+            "    the file and nothing is emitted on stdout.  Without --output,\n"
+            "    the full structured JSON (including the 'transcript' array) is\n"
+            "    written to stdout.\n"
+            "\n"
+            "meeting participant data:\n"
+            "  The VTT metadata NOTE block and JSON output include categorised\n"
+            "  participant information extracted from four sources:\n"
+            "\n"
+            "    Organiser     Meeting creator (from roster popover fibre tree)\n"
+            "    Invited       All chat thread members with names and emails\n"
+            "    Speakers      Members who spoke (from Recap Speakers tab)\n"
+            "    Attendees     Members who joined the call (from Event/Call partlist)\n"
+            "\n"
+            "  RSVP tracking data (accepted, tentative, declined, no response) is\n"
+            "  extracted from the meeting Details tab when available and applied to\n"
+            "  the Invited list.  RSVP extraction is soft-failure: if the Details\n"
+            "  tab or Tracking panel is unavailable, the pipeline continues without\n"
+            "  RSVP data.\n"
+            "\n"
+            "  In the VTT NOTE block, lists with more than 10 members show a count\n"
+            "  instead of names.  When RSVP data is available, the Invited line\n"
+            "  includes a breakdown (e.g. '90 members (50 accepted, 5 tentative,\n"
+            "  2 declined, 33 no response)').\n"
+            "\n"
+            "  In JSON mode, each participant is a dict with 'name', 'email', and\n"
+            "  optionally 'rsvp_status' fields.  The JSON keys are:\n"
+            "    organiser      dict with name and email\n"
+            "    invited        list of dicts (with rsvp_status when available)\n"
+            "    speakers_list  list of dicts\n"
+            "    attendees      list of dicts\n"
+            "\n"
+            "  Note: the 'attendees' list may be incomplete for large meetings\n"
+            "  due to server-side truncation of the Event/Call partlist XML.\n"
+            "\n"
+            "exit codes:\n"
+            "  0    Success\n"
+            "  1    Invalid arguments or missing configuration (BAD_ARGS)\n"
+            "  2    Teams/CDP not running or not responding (CDP_UNAVAILABLE)\n"
+            "  3    Meeting not found after all retries (MEETING_NOT_FOUND)\n"
+            "  4    Transcript download failed (DOWNLOAD_FAILED)\n"
+            "  5    Output file verification failed (VERIFICATION_FAILED)\n"
+            "  6    Tenant not found in available tenants (TENANT_NOT_FOUND)\n"
+            "  130  Interrupted by SIGINT (Ctrl+C)\n"
+            "  143  Terminated by SIGTERM\n"
+            "\n"
+            "output modes:\n"
+            "  --output PATH  --format vtt    File written, nothing on stdout\n"
+            "  --output PATH  --format json   File written, nothing on stdout\n"
+            "  (no --output)  --format vtt    VTT content on stdout\n"
+            "  (no --output)  --format json   Structured JSON on stdout\n"
+            "  --dry-run      --format vtt    Summary logged to stderr\n"
+            "  --dry-run      --format json   JSON metadata on stdout (no VTT)\n"
+            "  --dry-run      --output PATH   Error (incompatible)\n"
+            "  --list-tenants --format vtt    Tenant table on stdout\n"
+            "  --list-tenants --format json   Tenant JSON array on stdout\n"
+            "  --list-tenants --output PATH   Tenant list written to file\n"
+            "  --list-transcripts             Meeting table on stdout (today)\n"
+            "  --list-transcripts N           Meeting table on stdout (N days)\n"
+            "  --list-transcripts --format json  Meeting JSON array on stdout\n"
+            "  --list-transcripts --format vtt   ERROR (incompatible)\n"
+            "  --list-transcripts -o PATH     Meeting list written to file\n"
+            "\n"
+            "json output schema (--format json, all components):\n"
+            "  {\n"
+            '    "status": "ok",\n'
+            '    "meeting": "Weekly Standup",\n'
+            '    "start": "2026-04-14T10:00+01:00",\n'
+            '    "end": "2026-04-14T10:30+01:00",\n'
+            '    "organiser": {"name": "Alice", "email": "alice@example.com"},\n'
+            '    "invited": [\n'
+            '      {"name": "Bob", "email": "bob@x.com", "rsvp_status": "accepted"}\n'
+            "    ],\n"
+            '    "speakers_list": [{"name": "Alice", "email": "alice@x.com"}],\n'
+            '    "attendees": [{"name": "Alice", "email": "alice@x.com"}],\n'
+            '    "chat": [\n'
+            "      {\n"
+            '        "author": "Bob", "text": "Hello",\n'
+            '        "reactions": [{"type": "like", "count": 1, "users": ["Alice"]}],\n'
+            '        "offset": "00:05:12.000"\n'
+            "      }\n"
+            "    ],\n"
+            '    "transcript": [\n'
+            "      {\n"
+            '        "id": 1, "start": "00:00:03.366", "end": "00:00:09.117",\n'
+            '        "start_sec": 3.366, "end_sec": 9.117,\n'
+            '        "speaker": "Alice", "text": "Good morning everyone."\n'
+            "      }\n"
+            "    ],\n"
+            '    "parts": 1, "cues": 342,\n'
+            '    "speakers": {"Alice": 180, "Bob": 162},\n'
+            '    "file_size": 48210, "chat_messages": 1\n'
+            "  }\n"
+            "\n"
+            "json output schema (--transcript no --chat yes --metadata no):\n"
+            "  {\n"
+            '    "status": "ok",\n'
+            '    "meeting": "Weekly Standup",\n'
+            '    "start": "2026-04-14T10:00+01:00",\n'
+            '    "end": "2026-04-14T10:30+01:00",\n'
+            '    "chat": [\n'
+            '      {"author": "Bob", "text": "Hello", "reactions": null,\n'
+            '       "offset": "00:05:12.000"}\n'
+            "    ]\n"
+            "  }\n"
+            "\n"
+            "json output schema (--transcript no --chat no --metadata yes):\n"
+            "  {\n"
+            '    "status": "ok",\n'
+            '    "meeting": "Weekly Standup",\n'
+            '    "start": "2026-04-14T10:00+01:00",\n'
+            '    "end": "2026-04-14T10:30+01:00",\n'
+            '    "organiser": {"name": "Alice", "email": "alice@example.com"},\n'
+            '    "invited": [\n'
+            '      {"name": "Bob", "email": "bob@x.com", "rsvp_status": "accepted"}\n'
+            "    ],\n"
+            '    "speakers_list": [{"name": "Alice", "email": "alice@x.com"}],\n'
+            '    "attendees": [{"name": "Alice", "email": "alice@x.com"}]\n'
+            "  }\n"
+            "\n"
+            "json output schema (--transcript yes --chat no --metadata no):\n"
+            "  {\n"
+            '    "status": "ok",\n'
+            '    "meeting": "Weekly Standup",\n'
+            '    "start": "2026-04-14T10:00+01:00",\n'
+            '    "end": "2026-04-14T10:30+01:00",\n'
+            '    "parts": 1, "cues": 342,\n'
+            '    "speakers": {"Alice": 180, "Bob": 162},\n'
+            '    "file_size": 48210,\n'
+            '    "transcript": [{...cues...}]\n'
+            "  }\n"
+            "\n"
+            "json output schema (error):\n"
+            "  {\n"
+            '    "status": "error",\n'
+            '    "code": "MEETING_NOT_FOUND",\n'
+            '    "message": "Could not find target 2026-04-14 in search results.",\n'
+            '    "step": "step5"\n'
+            "  }\n"
+            "\n"
+            "json field reference:\n"
+            "  status        string   always present ('ok' or 'error')\n"
+            "  meeting       string   meeting title\n"
+            "  start         string   ISO 8601 meeting start time\n"
+            "  end           string   ISO 8601 meeting end time (when parseable)\n"
+            "  dry_run       boolean  present only in --dry-run mode\n"
+            "  organiser     object   {name, email} (--metadata yes)\n"
+            "  invited       array    [{name, email, rsvp_status?}] (--metadata yes)\n"
+            "  speakers_list array    [{name, email}] (--metadata yes)\n"
+            "  attendees     array    [{name, email}] (--metadata yes + attendance data)\n"
+            "  chat          array    [{author, text, reactions, offset}] (--chat yes;\n"
+            "                         offset may be null when not computable)\n"
+            "  chat_messages integer  count (all-components mode only)\n"
+            "  parts         integer  transcript part count (--transcript yes)\n"
+            "  cues          integer  total cue count (--transcript yes)\n"
+            "  speakers      object   {name: cue_count} (--transcript yes)\n"
+            "  file_size     integer  VTT content size in bytes (--transcript yes)\n"
+            "  transcript    array    [{id, start, end, start_sec, end_sec, speaker, text}]\n"
+            "                         (--transcript yes)\n"
+            "  code          string   machine-stable error code (errors only)\n"
+            "  message       string   human-readable error description (errors only)\n"
+            "  step          string   pipeline step that failed (runtime errors)\n"
+            "\n"
+            "error codes (machine-stable, used in text prefix and JSON 'code' field):\n"
+            "  BAD_ARGS              Invalid CLI arguments or missing config\n"
+            "  CDP_UNAVAILABLE       Teams/CDP not running or not responding\n"
+            "  RESTART_BLOCKED       Teams restart blocked by active/unknown call state\n"
+            "  NO_TARGETS            No Teams page targets found via CDP\n"
+            "  SEARCH_FAILED         Search results did not appear\n"
+            "  MEETING_NOT_FOUND     Meeting not found in search results\n"
+            "  RECAP_NOT_FOUND       Recap tab not found after navigation\n"
+            "  TRANSCRIPT_NOT_FOUND  Transcript tab not found\n"
+            "  IFRAME_NOT_FOUND      No transcript iframe target\n"
+            "  DOWNLOAD_FAILED       VTT download failed\n"
+            "  VERIFICATION_FAILED   Output file is invalid\n"
+            "  TENANT_NOT_FOUND      Tenant not in available tenants list\n"
+            "  INTERRUPTED           Process interrupted by SIGINT\n"
+            "  TERMINATED            Process terminated by SIGTERM\n"
+            "\n"
+            "mcp server:\n"
+            "  An MCP (Model Context Protocol) server is available for tool-use by\n"
+            "  AI agents.  Start with: teams-transcripts-mcp\n"
+            "  Or on a network port: teams-transcripts-mcp --port 8080\n"
+            "  Recommended tool: download(meeting_id=UUID) -- the unified entry point.\n"
+            "  Also available: restart_teams, list_tenants, list_transcripts,\n"
+            "    download_by_meeting_id, download_all, download_transcript,\n"
+            "    download_chat, download_meeting_metadata, and UUID-based variants.\n"
+            "  AI agents should prefer MCP tools over direct CLI invocation.\n"
+            "  STDIO transport (default) for subprocess spawning by MCP clients.\n"
+            "  SSE transport (--port) for network access.\n"
+        ),
+    )
+    p.add_argument(
+        "--list-tenants",
+        action="store_true",
+        default=False,
+        help=(
+            "List all Azure AD tenants the signed-in user can access, "
+            "then exit.  Output includes tenant name, primary domain, "
+            "and tenant ID.  The current tenant is marked with *.  "
+            "Use the name or domain value with --tenant in a subsequent "
+            "invocation.  Incompatible with --meeting, --meeting-id, and --datetime."
+        ),
+    )
+    p.add_argument(
+        "--list-transcripts",
+        nargs="?",
+        const=1,
+        type=int,
+        default=None,
+        metavar="DAYS",
+        help=(
+            "List meetings with transcripts, then exit.  Accepts an optional "
+            "number of days to look back (default: 1 = today only; must be >= 1).  Output is "
+            "a plain-text table by default; use --format json for structured "
+            "output.  --format vtt is not valid with this flag.  Use --output "
+            "to write the listing to a file instead of stdout.  When --tenant "
+            "is specified, only meetings from that tenant are listed.  Without "
+            "--tenant, all signed-in tenants are queried and results aggregated."
+        ),
+    )
+    meeting_group = p.add_mutually_exclusive_group()
+    meeting_group.add_argument(
+        "--meeting",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Meeting name to search for in Teams.  This is typed into the Teams "
+            "search bar, so it should match the meeting title as it appears in the "
+            "Teams UI.  For best results use the full meeting title.  "
+            "Mutually exclusive with --meeting-id and --call-id."
+        ),
+    )
+    meeting_group.add_argument(
+        "--meeting-id",
+        default=None,
+        metavar="UUID",
+        dest="meeting_id",
+        help=(
+            "Meeting UUID to download (from --list-transcripts ID column).  "
+            "Identifies a meeting thread.  For non-recurring meetings this is "
+            "unique; for recurring meetings all occurrences share the same UUID.  "
+            "Use --call-id instead for unambiguous occurrence targeting.  "
+            "The tool resolves the meeting subject and date via the MCPS API "
+            "and then navigates as if --meeting were used.  "
+            "Mutually exclusive with --meeting and --call-id.  Do not pass "
+            "--datetime with this flag (the date is resolved automatically)."
+        ),
+    )
+    meeting_group.add_argument(
+        "--call-id",
+        default=None,
+        metavar="CALL_ID",
+        dest="call_id",
+        help=(
+            "Call identifier to download (from --list-transcripts Call ID column).  "
+            "Uniquely identifies a specific occurrence of a meeting, including "
+            "recurring meetings.  This is the preferred identifier when targeting "
+            "a specific occurrence.  The tool resolves the meeting subject, date, "
+            "and thread via the MCPS API.  "
+            "Mutually exclusive with --meeting and --meeting-id.  Do not pass "
+            "--datetime with this flag (the date is resolved automatically)."
+        ),
+    )
+    p.add_argument(
+        "--datetime",
+        default=None,
+        metavar="YYYY-MM-DD[THH:MM]",
+        dest="datetime",
+        help=(
+            "Target meeting date, optionally with time, in ISO 8601 format. "
+            "Only valid with --meeting; incompatible with --meeting-id "
+            "(the date is resolved automatically from the UUID).  "
+            "Defaults to today's date when omitted.  "
+            "Date only (e.g. 2026-04-22) selects the first occurrence on that "
+            "date.  Date with time (e.g. 2026-04-22T14:00) disambiguates when "
+            "there are multiple meetings with the same name on the same day.  "
+            "The time is matched against the start time shown in the Teams "
+            "occurrence dropdown (e.g. '22 April 2026 14:00 - 15:00')."
+        ),
+    )
+    p.add_argument(
+        "--output",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Output file path.  The file is created (or overwritten) at "
+            "this path.  Parent directories must already exist.  When "
+            "omitted, content is written to stdout.  The file format is "
+            "determined by --format (VTT or structured JSON)."
+        ),
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help=(
+            "Find the meeting, load Recap only when transcript or metadata is "
+            "requested, detect parts, extract safe roster metadata when metadata "
+            "or chat is requested, then exit without downloading transcripts, "
+            "extracting chat, or opening Details tracking.  Incompatible with --output."
+        ),
+    )
+    p.add_argument(
+        "--gcp-project",
+        default=None,
+        metavar="PROJECT_ID",
+        help=(
+            "Google Cloud project ID for Vertex AI API calls.  Falls back to "
+            "the GOOGLE_CLOUD_PROJECT environment variable.  A value must be "
+            "provided via either this flag or the environment variable."
+        ),
+    )
+    p.add_argument(
+        "--port",
+        type=int,
+        default=9333,
+        metavar="PORT",
+        help=(
+            "CDP remote debugging port that Teams is listening on "
+            "(default: %(default)s).  Must match the value passed to Teams via "
+            "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS.  Must be between 1 and 65535."
+        ),
+    )
+    p.add_argument(
+        "--force-restart",
+        action="store_true",
+        default=False,
+        help=(
+            "Allow Teams to be killed and relaunched even when an active call is "
+            "detected or call state cannot be determined. This may interrupt a live "
+            "call; use only when interruption is explicitly intended."
+        ),
+    )
+    p.add_argument(
+        "--tenant",
+        default=None,
+        metavar="DOMAIN",
+        help=(
+            "Azure AD tenant domain to verify before downloading (e.g. "
+            "'abccorp.com', 'contoso.onmicrosoft.com').  When specified, the tool "
+            "checks that Teams is signed into the matching tenant and "
+            "automatically switches if needed (by killing and relaunching "
+            "Teams).  Exits with code 6 if the tenant is not in the "
+            "available tenants list.  Falls back to the TEAMS_TENANT "
+            "environment variable.  Omit to skip tenant checking."
+        ),
+    )
+    p.add_argument(
+        "--gcp-region",
+        default=None,
+        metavar="REGION",
+        help=(
+            "Vertex AI region for model inference (default: 'global').  Falls "
+            "back to the CLOUD_ML_REGION environment variable."
+        ),
+    )
+    p.add_argument(
+        "--model",
+        default=None,
+        metavar="MODEL_ID",
+        help=(
+            "Anthropic model ID for the LLM agent used in non-deterministic "
+            "navigation steps (default: 'claude-haiku-4-5').  Falls back to "
+            "the MODEL_ID environment variable.  Haiku is recommended for speed "
+            "and cost; the agent prompts are simple classification tasks."
+        ),
+    )
+    p.add_argument(
+        "--adc",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Path to a Google Application Default Credentials JSON file.  "
+            "Falls back to the GOOGLE_ADC environment variable, then to "
+            "~/.config/gcloud/application_default_credentials.json."
+        ),
+    )
+
+    verbosity = p.add_mutually_exclusive_group()
+    verbosity.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        default=False,
+        help="Suppress all diagnostic output on stderr.  Errors and "
+        "structured output (--format json) are still emitted.",
+    )
+    verbosity.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        default=False,
+        help="Emit additional diagnostic detail on stderr (CDP payloads, "
+        "agent prompts, React fibre data sizes).",
+    )
+
+    p.set_defaults(_format_explicit=False)
+    p.add_argument(
+        "--format",
+        dest="output_format",
+        choices=["vtt", "json"],
+        default="vtt",
+        action=_ExplicitFormatAction,
+        help="Output format.  'vtt' (default) writes WebVTT content.  "
+        "'json' writes structured JSON with a 'transcript' array of cue "
+        "objects.  Both formats write to --output (file) or stdout.",
+    )
+
+    p.add_argument(
+        "--transcript",
+        choices=["yes", "no"],
+        default="yes",
+        help="Include transcript cues in output (default: yes).  When 'no', "
+        "the transcript download is skipped and output is forced to JSON.  "
+        "Combine with --chat no and --metadata no only with --dry-run for a "
+        "pure meeting-exists check.",
+    )
+    p.add_argument(
+        "--chat",
+        choices=["yes", "no"],
+        default="yes",
+        help="Include chat messages in output (default: yes).  When 'no', "
+        "chat messages are omitted from output.  If --metadata yes, the tool may "
+        "still read Event/Call messages internally to build attendee metadata.",
+    )
+    p.add_argument(
+        "--metadata",
+        choices=["yes", "no"],
+        default="yes",
+        help="Include meeting participant metadata in output (default: yes).  "
+        "When 'no', participant data (organiser, invited, speakers, "
+        "attendees, RSVP) is omitted from the output.  Roster extraction "
+        "still runs if --chat yes (for author name resolution).",
+    )
+
+    return p.parse_args()
+
+
+class _ExplicitFormatAction(argparse.Action):
+    """Record that ``--format`` was supplied explicitly."""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        setattr(namespace, self.dest, values)
+        namespace._format_explicit = True
+
+
+# ---------------------------------------------------------------------------
+# Configuration resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_config(
+    args: argparse.Namespace,
+    *,
+    env_override: dict[str, str | None] | None = None,
+) -> MeetingConfig:
+    """Resolve all configuration from CLI args, env vars, and defaults.
+
+    Returns a frozen :class:`~domain.models.MeetingConfig`.  Does not
+    mutate any global state.
+
+    Calls ``exit_error()`` with the appropriate ``format_json`` setting
+    for validation failures, producing both human-readable stderr output
+    and (when ``--format json``) structured JSON on stdout.
+
+    Args:
+        args: Parsed CLI arguments from :func:`parse_args`.
+        env_override: Optional mapping of environment variable names to
+            values (or ``None`` to unset).  Used by tests to inject
+            environment without patching ``os.environ`` externally.
+
+    Returns:
+        A frozen ``MeetingConfig`` instance.
+    """
+    # Apply env overrides for the duration of resolution
+    saved_env: dict[str, str | None] = {}
+    if env_override:
+        for k, v in env_override.items():
+            saved_env[k] = os.environ.get(k)
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+    try:
+        return _resolve_config_inner(args)
+    finally:
+        # Restore original environment
+        if env_override:
+            for k in env_override:
+                original = saved_env[k]
+                if original is None:
+                    os.environ.pop(k, None)
+                else:
+                    os.environ[k] = original
+
+
+def _format_explicitly_set(args: argparse.Namespace) -> bool:
+    """Check whether --format was explicitly provided on the command line.
+
+    ``parse_args()`` records this via :class:`_ExplicitFormatAction`.  The
+    fallback keeps direct tests that construct ``argparse.Namespace`` objects
+    compatible without consulting global ``sys.argv``.
+    """
+    return bool(getattr(args, "_format_explicit", False))
+
+
+# ---------------------------------------------------------------------------
+# Environment variable resolution (pydantic-settings)
+# ---------------------------------------------------------------------------
+
+
+class _GcpSettings(BaseSettings):
+    """Resolve GCP and tenant configuration from environment variables.
+
+    Each field maps to one environment variable (case-insensitive match).
+    CLI arguments take precedence and are merged in
+    ``_resolve_config_inner()``.
+
+    Fields:
+        google_cloud_project: GCP project ID (``GOOGLE_CLOUD_PROJECT``).
+        cloud_ml_region: Vertex AI region (``CLOUD_ML_REGION``).
+        model_id: LLM model identifier (``MODEL_ID``).
+        google_adc: Path to ADC JSON (``GOOGLE_ADC``).
+        teams_tenant: Tenant domain (``TEAMS_TENANT``).
+    """
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    google_cloud_project: str | None = None
+    cloud_ml_region: str = "global"
+    model_id: str = "claude-haiku-4-5"
+    google_adc: str = "~/.config/gcloud/application_default_credentials.json"
+    teams_tenant: str | None = None
+
+
+def _resolve_config_inner(args: argparse.Namespace) -> MeetingConfig:
+    """Internal resolution logic (env overrides already applied)."""
+    format_json = args.output_format == "json"
+
+    # --meeting, --meeting-id, and --call-id mutual exclusivity is enforced by
+    # argparse.  Check that at least one is provided (argparse group is not
+    # required because list modes don't need either).
+    if not args.meeting and not args.meeting_id and not args.call_id:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "One of --meeting, --meeting-id, or --call-id is required.",
+            format_json=format_json,
+        )
+
+    # --datetime is incompatible with --meeting-id (date is resolved from MCPS).
+    if args.meeting_id and args.datetime:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--datetime is incompatible with --meeting-id. "
+            "The meeting date is resolved automatically from the UUID.",
+            format_json=format_json,
+        )
+
+    # --datetime is incompatible with --call-id (date is resolved from MCPS).
+    if args.call_id and args.datetime:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--datetime is incompatible with --call-id. "
+            "The meeting date is resolved automatically from the call ID.",
+            format_json=format_json,
+        )
+
+    if args.meeting_id:
+        try:
+            args.meeting_id = str(UUID(args.meeting_id))
+        except ValueError:
+            exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"Invalid meeting ID '{args.meeting_id}'. Expected UUID.",
+                format_json=format_json,
+            )
+
+    if not 1 <= args.port <= 65535:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            f"Invalid port '{args.port}'. Expected a value from 1 to 65535.",
+            format_json=format_json,
+        )
+
+    # --datetime defaults to today's date when omitted (only for --meeting mode).
+    if not args.datetime and not args.meeting_id and not args.call_id:
+        args.datetime = datetime.now(tz=timezone.utc).astimezone().date().isoformat()
+
+    # Resolve GCP and tenant settings from env vars (CLI args take precedence)
+    settings = _GcpSettings()
+
+    project = args.gcp_project or settings.google_cloud_project
+    if not project:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--gcp-project not provided and GOOGLE_CLOUD_PROJECT not set.",
+            format_json=format_json,
+        )
+
+    model = args.model or settings.model_id
+    region = args.gcp_region or settings.cloud_ml_region
+    adc = args.adc or os.path.expanduser(settings.google_adc)
+
+    # Parse --datetime: accept YYYY-MM-DD or YYYY-MM-DDTHH:MM
+    # When --meeting-id or --call-id is used, date is populated later from MCPS resolution.
+    target_date = ""
+    target_time = None
+    dt_raw = args.datetime
+    if dt_raw:
+        if "T" in dt_raw:
+            date_part, time_part = dt_raw.split("T", 1)
+            # Validate date
+            try:
+                date.fromisoformat(date_part)
+            except ValueError:
+                exit_error(
+                    EXIT_BAD_ARGS,
+                    "BAD_ARGS",
+                    f"Invalid date '{date_part}'. Expected YYYY-MM-DD.",
+                    format_json=format_json,
+                )
+            # Validate time (HH:MM with valid ranges)
+            if not re.match(r"^\d{2}:\d{2}$", time_part):
+                exit_error(
+                    EXIT_BAD_ARGS,
+                    "BAD_ARGS",
+                    f"Invalid time format '{time_part}'. Expected HH:MM.",
+                    format_json=format_json,
+                )
+            hh, mm = time_part.split(":")
+            if not (0 <= int(hh) <= 23 and 0 <= int(mm) <= 59):
+                exit_error(
+                    EXIT_BAD_ARGS,
+                    "BAD_ARGS",
+                    f"Invalid time '{time_part}'. Hours must be 00-23, minutes 00-59.",
+                    format_json=format_json,
+                )
+            target_time = time_part
+            target_date = date_part
+        else:
+            try:
+                date.fromisoformat(dt_raw)
+            except ValueError:
+                exit_error(
+                    EXIT_BAD_ARGS,
+                    "BAD_ARGS",
+                    f"Invalid date '{dt_raw}'. Expected YYYY-MM-DD or YYYY-MM-DDTHH:MM.",
+                    format_json=format_json,
+                )
+            target_date = dt_raw
+
+    # Validate flag combinations
+    if args.dry_run and args.output:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--dry-run and --output are incompatible. Dry-run does not produce a file.",
+            format_json=format_json,
+        )
+
+    # Resolve component flags
+    include_transcript = args.transcript == "yes"
+    include_chat = args.chat == "yes"
+    include_metadata = args.metadata == "yes"
+
+    # At least one component must be included for real extraction.  Dry-run may
+    # disable all components as a pure meeting-exists check.
+    if not include_transcript and not include_chat and not include_metadata and not args.dry_run:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "At least one of --transcript, --chat, or --metadata must be 'yes'.",
+            format_json=format_json,
+        )
+
+    # --transcript no requires JSON format (VTT without cues is meaningless)
+    if not include_transcript and args.output_format == "vtt":
+        # Check whether user explicitly passed --format vtt
+        # If so, error.  If --format was left at default, override to json.
+        if _format_explicitly_set(args):
+            exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                "--format vtt requires --transcript yes. "
+                "Use --format json when transcript is excluded.",
+                format_json=False,
+            )
+        args.output_format = "json"
+        format_json = True
+
+    # When --output is omitted (and not --dry-run), use a temp file
+    # internally so the file-based pipeline works unchanged.  The temp
+    # file content is written to stdout (or embedded in JSON) at the end.
+    # When transcript is excluded, no temp file is needed (JSON-only output).
+    output_to_stdout = not args.dry_run and args.output is None
+    if output_to_stdout and include_transcript:
+        tmp_fd, output_path = tempfile.mkstemp(suffix=".vtt")
+        os.close(tmp_fd)
+    else:
+        output_path = args.output  # None when --dry-run or --transcript no without --output
+
+    # Resolve tenant: CLI flag takes precedence over environment variable
+    tenant = args.tenant or settings.teams_tenant or None
+
+    return MeetingConfig(
+        meeting=args.meeting or "",
+        meeting_id=args.meeting_id,
+        call_id=args.call_id,
+        date=target_date,
+        time=target_time,
+        output=output_path,
+        output_to_stdout=output_to_stdout,
+        dry_run=args.dry_run,
+        port=args.port,
+        tenant=tenant,
+        gcp_project=project,
+        gcp_region=region,
+        model=model,
+        adc=adc,
+        output_format=args.output_format,
+        quiet=args.quiet,
+        verbose=args.verbose,
+        include_transcript=include_transcript,
+        include_chat=include_chat,
+        include_metadata=include_metadata,
+        force_restart=getattr(args, "force_restart", False),
+    )