Production runbook

Use this page when preparing a target Mac, checking runtime readiness, packaging a build, or validating the app after a release sprint.

npm run check

Release command path

These commands mirror the production release rules in the sprint plan and keep the packaged app as the real acceptance target.

npm install

Install Electron app dependencies.

npm run check

Run TypeScript and unit tests.

npm run build

Build Electron main, preload, and renderer output.

npx electron-builder --mac --arm64

Package a macOS arm64 build for smoke testing.

scripts/macos_install_helper.sh

Audit target-Mac permissions, runtimes, models, ffmpeg, loopback input, Ollama, and provider keys.

Target Mac setup

Install Node.js and run npm install for development.
Run scripts/setup_parakeet_runtime.sh to create the app-managed Parakeet environment.
Run scripts/setup_diarization_runtime.sh only when local speaker diarization is needed.
Install ffmpeg so audio can be normalized before transcription.
Download the Parakeet model cache from Settings before the first real meeting.
Save a Hugging Face token before downloading pyannote.
Configure Ollama or a cloud summary provider before generating production summaries.
Run scripts/macos_install_helper.sh on a target Mac to audit the full local setup.

Manual smoke test

Launch the app and verify the agenda loads demo or connected calendar events.
Open macOS privacy settings from the permission strip.
Start a quick recording and approve microphone permission.
Stop recording and confirm mic.webm, system.webm, and mixed.webm exist when tracks are available.
Run transcription and verify Parakeet output appears.
Confirm pyannote is used when available or fallback speaker labels appear with a visible warning.
Generate a summary with the selected provider and detail level.
Copy the follow-up draft and export Markdown or PDF.
Package macOS arm64 and smoke test the app bundle, not just the dev shell.

Readiness matrix

The site separates complete foundations from partial operational work so the current production posture is easy to review.

AreaStatusOwnerEvidence

Secure desktop shellImplementedElectron main/preloadContext isolation, renderer sandboxing, CSP, typed preload IPC, and request schemas are already present.

Recording foundationImplementedRenderer capture and RecordingServiceMicrophone/system/mixed capture, recording sessions, track paths, and playback track selection are implemented.

Managed transcription jobsImplementedTranscriptionServiceLifecycle phases, cancel, retry, process termination, and polling are complete.

Runtime diagnosticsPartialSettings and runtime servicesStatus checks exist; a full runtime/model manager page and diagnostics export are planned.

Export coveragePartialExportServiceBackend formats exist; richer export UI, high-fidelity DOCX, and PDF polish remain.

AutomationPlannedQuality sprintUnit tests exist; packaged-app smoke automation is planned for Sprint 7.

Provider operations

Summary providers are explicit: local by default, cloud only when configured, and experimental where the app depends on user-local tools.

AreaStatusOwnerEvidence

OllamaLocal defaulthttp://127.0.0.1:11434Health check uses /api/tags and summary generation uses /api/generate with stream disabled.

OpenRouterCloud optionalOPENROUTER_API_KEYUses an OpenAI-compatible chat completions endpoint.

OpenAI-compatibleCloud optionalOPENAI_API_KEY by defaultCalls /chat/completions against the configured base URL.

Codex CLIExperimentalLocal codex loginShells out to the local codex executable and does not use an app API key.

Offline demoFallbackBundled rule pathAlways available when provider-backed summarization is not configured.

Security controls

Production setup should preserve the local-first boundaries and make permission repair paths visible.

Narrow IPC surface

Renderer calls pass through typed preload APIs and zod-validated request schemas before main-process services perform filesystem or provider work.

Local vault ownership

Audio, transcript, summary, and export artifacts stay under local filesystem control, with guardrails for path handling and selective deletion.

Credential checks

Provider credentials can be stored in app settings or supplied by environment variables, and the UI reports saved and environment status separately.

Permission diagnostics

The app surfaces microphone, system audio, and calendar permission status, plus direct paths to macOS settings when repair is needed.