# InkIt Documentation

> Reference for InkIt, a macOS 14+ dictation app that streams audio to Cartesia Ink-2 STT, optionally polishes transcripts via BYOK LLM providers, and pastes into the focused application. Covers setup, the dictation pipeline, configuration keys, API contracts, troubleshooting, and contributor build workflows.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/llms-full.txt)
- [Complete Markdown alias](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b.md)
- [Human interactive docs](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b)
- [GitHub repository](https://github.com/cartesia-ai/InkIt)

## Repository

- Repository: cartesia-ai/InkIt

- Generated: 2026-06-15T22:14:29.136Z
- Updated: 2026-06-15T22:24:41.349Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22

## Pages

- [Overview](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/01-overview.md): What InkIt exposes: global hotkey dictation, Cartesia Ink-2 streaming STT, optional LLM polish, notch HUD feedback, transcript history, and Sparkle updates. Runtime requirements (macOS 14+, Apple silicon), primary entry points, and the shortest path from install to first pasted transcript.
- [Installation](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/02-installation.md): Install InkIt from the release DMG or build from source with XcodeGen. Prerequisites, bundle identifier, deployment target, entitlements (no App Sandbox), and the requirement to replace `/Applications/InkIt.app` after local builds.
- [Quickstart](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/03-quickstart.md): First successful dictation: launch InkIt, complete onboarding (permissions, Cartesia API key, Try It trial), hold or toggle the default hotkey, speak, release, and verify text pastes at the cursor. Expected HUD states, success signals, and recovery when no editable field is focused.
- [Dictation pipeline](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/04-dictation-pipeline.md): End-to-end flow from hotkey press through audio capture (16 kHz PCM), Cartesia WebSocket STT, optional TranscriptRewriter polish, FocusedEditable target resolution, PasteService Cmd+V insertion, and TranscriptHistoryStore persistence. Latency stages and prewarm behavior.
- [Dictation state machine](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/05-dictation-state-machine.md): DictationState lifecycle: idle, recording, finalizing, rewriting, pasting, heldInHistory, and error. Transitions on hotkey press/release, STT completion, polish outcome, paste result, and empty-transcript collapse. audioReady and liveTranscript HUD coupling.
- [Permissions model](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/06-permissions-model.md): Microphone (AVCaptureDevice) and Accessibility (AXIsProcessTrusted) requirements, PermissionState tri-state (granted, notRequested, needsManual), onboarding prompt flow, polling strategy, and the silent relaunch after Accessibility grant.
- [Hotkey bindings](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/07-hotkey-bindings.md): HotkeyBinding variants: Carbon RegisterEventHotKey combos, Fn/Globe via CGEventTap with suppression, and bare modifier keys. DictationMode hold vs toggle semantics, isValidShortcut reserved-system checks, and HotkeyManager dedicated tap threads.
- [Configure Cartesia API key](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/08-configure-cartesia-api-key.md): Obtain a Cartesia API key, enter it during onboarding or Settings, Keychain storage (account cartesiaAPIKey), advisory validation via APIKeyValidator, and persisted cartesiaKeyInvalid / cartesiaOutOfCredits flags that drive Home service-issue cards.
- [Configure Polish](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/09-configure-polish.md): Enable optional transcript polish: pick an LLMProvider (Groq recommended), store per-provider keys in Keychain, select rewriteModel, toggle correctionEnabled, and interpret PolishUIState (setup, on, paused, keyBroken). Onboarding Groq-only validation path.
- [Configure hotkeys and dictation mode](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/10-configure-hotkeys-and-dictation-mode.md): Record a global shortcut in Settings, switch between hold-to-talk and hands-free toggle, validate against reserved macOS shortcuts, and verify registration after Accessibility is granted. notchHorizontalPosition and playFeedbackSounds side settings.
- [Input device selection](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/11-input-device-selection.md): Pin a preferred microphone by CoreAudio UID in Settings, fall back to system default when unplugged, Bluetooth A2DP→HFP switch delay and audioReady HUD cue, and the readyLevelThreshold / readyFallbackDelay backstop in AudioCaptureService.
- [Settings reference](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/12-settings-reference.md): All persisted SettingsStore keys: UserDefaults fields (appearance, hotkey, dictationMode, notch position, service-issue flags), Keychain accounts (cartesiaAPIKey, llm.{provider}), SMAppService launchAtLogin, and derived properties transcriptionIssue / polishIssue.
- [Cartesia STT reference](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/13-cartesia-stt-reference.md): CartesiaStreamingClient WebSocket contract: wss://api.cartesia.ai/stt/turns/websocket, model ink-2, encoding pcm_s16le, sample_rate 16000, cartesia_version 2026-03-01, server events, client close message, pending audio buffer, and STTFailure classification table with notchMessage strings.
- [LLM providers reference](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/14-llm-providers-reference.md): LLMProvider enum: Groq, Gemini, OpenAI, Anthropic endpoints, default models, rewriteTimeout ceilings, validationRequest probes, keyURL/billingURL, OpenAI-compatible vs Anthropic Messages API shapes, and RewriteFailure reason codes.
- [Paste and focus reference](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/15-paste-and-focus-reference.md): PasteService clipboard session tagging, Cmd+V synthesis, timing constants, FocusedEditable AX budget walk, Chromium enableWebAccessibility prewarm, heldInHistory when no editable field, and TargetAppSnapshot paste-target resolution chain.
- [STT troubleshooting](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/16-stt-troubleshooting.md): Diagnose Cartesia transcription failures: STTFailure cases (offline, serverError, rateLimited, outOfCredits, invalidKey, unknown), notch vs Home card surfacing, graceful collapse on empty or benign disconnect, and STTFailureRoutingTests regression contracts.
- [Polish troubleshooting](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/17-polish-troubleshooting.md): Polish failure modes: RewriteFailure and PolishFailureReason, rate-limit Retry-After, timeout fallbacks to raw transcript, polishKeyInvalid and polishOutOfCredits persistence, history-row failure tooltips, and prewarm connection behavior.
- [Runtime troubleshooting](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/18-runtime-troubleshooting.md): Non-API runtime issues: duplicate InkIt bundle instances and Accessibility grants, Bluetooth mic profile delay, debugLoggingEnabled trace file at ~/Library/Logs/InkIt-debug.log, SwiftData persistence fallback, and notch HUD positioning on non-notch displays.
- [Build from source](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/19-build-from-source.md): Generate InkIt.xcodeproj with XcodeGen, open in Xcode 15+, Debug vs Release signing via Config/*.xcconfig, ad-hoc vs Developer ID notarized builds, Sparkle deep-sign post-build script, and install to /Applications.
- [Testing and CI](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/20-testing-and-ci.md): Run xcodebuild test locally, CI workflow steps (design-token check, xcodegen, Debug test, Release build), test targets (STTFailureRouting, AXBudget, TranscriptRecord, DebugLogFormatter), and design-token enforcement via tools/check-design-tokens.sh.
- [Release and distribution](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/21-release-and-distribution.md): Ship InkIt: tools/make-dmg.sh, tools/make-appcast.sh, tools/publish-release.sh, Sparkle SUFeedURL and UpdateManager custom pill flow, version bump via tools/bump-version.sh, and GitHub release assets (InkIt.dmg, appcast.xml).
- [Contributing](https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/pages/22-contributing.md): Fork-only contribution policy, feedback form, design-system token rules (Font.ink*, Color.canvas, ds-allow escape hatch), DESIGN_SYSTEM.md reference, commit-message conventions in AGENTS.md, and CI-enforced checks.

## Source Files

- `.github/CONTRIBUTING.md`
- `.github/workflows/ci.yml`
- `AGENTS.md`
- `Config/Debug.xcconfig`
- `Config/Signing.local.xcconfig.example`
- `Config/Signing.xcconfig`
- `Config/Sparkle.xcconfig`
- `DESIGN_SYSTEM.md`
- `InkIt/AppCoordinator.swift`
- `InkIt/AudioCaptureService.swift`
- `InkIt/AudioDeviceManager.swift`
- `InkIt/AudioPCMConverter.swift`
- `InkIt/AXTreeDumper.swift`
- `InkIt/CartesiaKeyValidator.swift`
- `InkIt/CartesiaStreamingClient.swift`
- `InkIt/ContextSnapshot.swift`
- `InkIt/DebugLog.swift`
- `InkIt/FeedbackSoundPlayer.swift`
- `InkIt/HotkeyManager.swift`
- `InkIt/Info.plist`
- `InkIt/InkIt.entitlements`
- `InkIt/InkItApp.swift`
- `InkIt/LLMProvider.swift`
- `InkIt/NotchHUD.swift`
- `InkIt/OnboardingView.swift`
- `InkIt/PasteService.swift`
- `InkIt/PermissionsService.swift`
- `InkIt/SettingsStore.swift`
- `InkIt/SettingsView.swift`
- `InkIt/TranscriptHistoryStore.swift`
- `InkIt/TranscriptRewriter.swift`
- `InkIt/TryItPracticeCard.swift`
- `InkIt/UpdateManager.swift`
- `InkItTests/AXBudgetTests.swift`
- `InkItTests/DebugLogFormatterTests.swift`
- `InkItTests/STTFailureRoutingTests.swift`
- `InkItTests/TranscriptRecordTests.swift`
- `LICENSE`
- `project.yml`
- `README.md`
- `tools/bump-version.sh`
- `tools/check-design-tokens.sh`
- `tools/make-appcast.sh`
- `tools/make-dmg.sh`
- `tools/publish-release.sh`