Initial open source preview

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @cmagnussen

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Report something broken in the macOS preview
+title: ""
+labels: bug
+assignees: ""
+---
+
+## What happened?
+
+
+## What did you expect?
+
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Environment
+
+- macOS version:
+- Mac model/chip:
+- Xcode version:
+- Did this happen before or after entering an OpenAI API key?:
+
+## Notes
+
+Do not paste API keys, private recordings, confidential transcripts, or screenshots with sensitive content.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for the preview
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## What would you like?
+
+
+## Why does it matter?
+
+
+## Possible approach
+
+
+## Privacy or security impact
+
+Would this send data to a new service, store more local data, or change how API keys are handled?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What changed?
+
+
+## Why?
+
+
+## How did you test it?
+
+
+## AI assistance
+
+Did you use AI-assisted coding tools? If yes, briefly mention where.
+
+## Checklist
+
+- [ ] I ran `./build.sh --debug` or explained why not.
+- [ ] I did not commit API keys, tokens, private recordings, or confidential transcripts.
+- [ ] I considered whether this changes privacy, security, or data flow.
+- [ ] I kept the change focused on the macOS preview scope.

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/secret-scan-patterns.txt

@@ -0,0 +1,32 @@
+# Secret hygiene patterns used by .github/workflows/ci.yml.
+# One extended-regex per line. Lines starting with `#` and blank lines are ignored.
+# Keep this file out of the scan via --exclude in the workflow.
+
+# OpenAI keys and config tokens
+sk-[A-Za-z0-9_-]{20,}
+OPENAI_API_KEY[[:space:]]*=
+APP_SECRET[[:space:]]*=
+
+# AWS access keys
+AKIA[0-9A-Z]{16}
+ASIA[0-9A-Z]{16}
+
+# GitHub tokens
+ghp_[A-Za-z0-9]{36}
+ghs_[A-Za-z0-9]{36}
+ghu_[A-Za-z0-9]{36}
+gho_[A-Za-z0-9]{36}
+github_pat_[A-Za-z0-9_]{20,}
+
+# Slack tokens and webhooks
+xox[abprs]-[A-Za-z0-9-]{10,}
+hooks\.slack\.com/services/
+
+# Discord webhooks
+discord(app)?\.com/api/webhooks/
+
+# Google API keys
+AIza[0-9A-Za-z_-]{35}
+
+# Generic private key blocks
+-----BEGIN [A-Z ]*PRIVATE KEY-----

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  build-macos:
+    name: Build macOS app
+    runs-on: macos-14
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Secret hygiene scan
+        run: |
+          patterns_file=.github/secret-scan-patterns.txt
+          if [ ! -f "$patterns_file" ]; then
+            echo "Missing $patterns_file"
+            exit 1
+          fi
+          pattern="$(grep -vE '^[[:space:]]*(#|$)' "$patterns_file" | paste -sd'|' -)"
+          if [ -z "$pattern" ]; then
+            echo "No patterns loaded from $patterns_file"
+            exit 1
+          fi
+          if grep -RInE \
+              --exclude-dir=.git \
+              --exclude=secret-scan-patterns.txt \
+              "$pattern" .; then
+            echo "Potential secret or private project reference found."
+            exit 1
+          fi
+
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_16.2.app || sudo xcode-select -s /Applications/Xcode.app
+
+      - name: Install XcodeGen
+        run: |
+          if ! command -v xcodegen >/dev/null 2>&1; then
+            brew install xcodegen
+          fi
+
+      - name: Build
+        run: ./build.sh --debug

.gitignore

@@ -0,0 +1,32 @@
+# Xcode
+*.xcuserstate
+*.xcuserdatad/
+xcuserdata/
+*.xcodeproj/
+DerivedData/
+.derivedData*/
+build/
+*.xcarchive
+*.dSYM
+*.dSYM.zip
+
+# macOS
+.DS_Store
+
+# Local app artifacts
+Blitztext.app
+dist/
+models/
+*.mlmodel
+*.mlmodelc/
+*.mlpackage/
+
+# Secrets and local config
+.env
+.env.*
+*.local
+Secrets.swift
+*.xcconfig
+
+# Tooling
+node_modules/

CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code Of Conduct
+
+Be kind, direct, and constructive.
+
+This is a small experimental project. Good discussion is welcome; personal attacks, harassment, or hostile behavior are not.
+
+If a conversation gets heated, slow down and move back to the concrete technical question.
+
+Maintainers may close, hide, or moderate issues, comments, and pull requests that make collaboration harder or unsafe.

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for taking a look at Blitztext macOS Preview.
+
+This repository is intentionally a preview. Contributions should make it easier to learn from, build, fork, or safely extend.
+
+## Good First Contributions
+
+- improve build instructions
+- fix confusing UI text
+- improve error messages
+- add tests around parsing or quality filters
+- document local model experiments
+- simplify setup
+
+## Before Opening A Pull Request
+
+Please include:
+
+- what changed
+- why it changed
+- how you tested it
+- whether you used AI-assisted coding tools
+
+Keep changes small when possible. Avoid unrelated cleanup in the same PR.
+
+## Local Build
+
+```bash
+./build.sh --debug
+```
+
+## Security And Privacy
+
+- Never commit API keys, tokens, private audio, or confidential transcripts.
+- Avoid adding telemetry, hosted services, or external dependencies without a clear issue first.
+- Call out privacy-impacting changes in the pull request description.
+- Keep the preview honest: do not describe remote OpenAI workflows as offline or local.
+
+## Project Boundaries
+
+This preview currently does not include:
+
+- other platforms
+- a hosted backend
+- packaged releases
+- bundled local model files
+- local text rewriting
+
+Those can be discussed in issues, but please keep PRs focused on the current macOS preview unless a maintainer agrees on a larger direction first.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blitztext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,146 @@
+# Blitztext App
+
+Blitztext App is an experimental open-source macOS menubar app for turning speech into text.
+
+It is intentionally small and unfinished. The goal is to make a real workflow visible and hackable: press a hotkey, speak, get text back, optionally rewrite it, and paste it into the app you were using.
+
+This is a learning and experimentation project, not a polished product.
+
+> Preview status: bring your own OpenAI API key, no hosted backend, no warranty, no support guarantee.
+
+## What It Does
+
+- **Blitztext**: record speech and transcribe it.
+- **Blitztext+**: record speech, transcribe it, then turn the rough draft into cleaner writing.
+- **Blitztext $%&!**: turn frustrated speech into a calmer message.
+- **Blitztext :)**: add fitting emojis to dictated text.
+
+## Important Preview Notes
+
+- macOS only.
+- Bring your own OpenAI API key.
+- No hosted Blitztext backend is included or provided.
+- In online mode, audio and text are sent directly from the app to the OpenAI API.
+- Optional local transcription via WhisperKit/CoreML if you install a compatible model locally.
+- `./build.sh` creates a locally ad-hoc-signed development app. No notarized release binary is provided.
+- Not production ready.
+- No warranty and no support guarantee.
+
+You are welcome to use, fork, adapt, and share this project under the license terms.
+
+The intent is not to ship a one-click finished app. The intent is to make a real AI workflow understandable: clone it, build it, read the code, change it, break it, fix it, and suggest improvements. If you only want to download something and never look inside, this preview will probably feel rough. If you want to learn how a small native macOS AI app is put together, you are in the right place.
+
+## Screenshots
+
+<table>
+  <tr>
+    <td><img src="docs/screenshots/online-mode.png" alt="Blitztext online transcription mode" width="420"></td>
+    <td><img src="docs/screenshots/local-mode.png" alt="Blitztext secure local transcription mode" width="420"></td>
+  </tr>
+  <tr>
+    <td><img src="docs/screenshots/local-model-picker.png" alt="Blitztext local model picker" width="420"></td>
+    <td><img src="docs/screenshots/settings-customize.png" alt="Blitztext settings and customization view" width="420"></td>
+  </tr>
+</table>
+
+## Requirements
+
+- macOS 14 or newer
+- Xcode 16 or newer (Swift 5.10), with Command Line Tools installed and selected for `xcodebuild`
+- [XcodeGen](https://github.com/yonaskolb/XcodeGen) to generate the Xcode project
+- For online transcription and rewriting: an OpenAI API key with access to:
+  - `whisper-1` for transcription
+  - `gpt-4o-mini` and optionally `gpt-4o` for rewriting
+- For local-only transcription: a WhisperKit CoreML model in:
+  `~/Library/Application Support/Blitztext/models/whisperkit/`
+
+The build also pulls one Swift Package dependency automatically:
+
+- [`argmax-oss-swift`](https://github.com/argmaxinc/argmax-oss-swift) (WhisperKit) — used for local on-device transcription.
+
+Install XcodeGen if needed:
+
+```bash
+brew install xcodegen
+```
+
+## Build And Run
+
+```bash
+git clone https://github.com/cmagnussen/blitztext-app.git
+cd blitztext-app
+./build.sh --run
+```
+
+For a local install into `/Applications`:
+
+```bash
+./build.sh --install --run
+```
+
+The generated `.app` is ad-hoc signed for local development only. Do not treat it as a trusted redistributable binary. A public binary release would need Developer ID signing and notarization.
+
+On first launch, either paste your own OpenAI API key for online workflows or install a WhisperKit CoreML model for local transcription. Rewriting workflows still require OpenAI.
+
+For fully local transcription, install a WhisperKit CoreML model and enable **Sicherer Lokaler Modus** in the app.
+
+For a slower, more explicit walkthrough, see [docs/setup.md](docs/setup.md).
+
+## Permissions
+
+Blitztext asks for:
+
+- **Microphone**: to record your voice.
+- **Accessibility**: to paste the result back into the app you were using.
+
+If you do not grant Accessibility permission, you can still copy results manually.
+
+## Data Flow
+
+The preview has no custom backend.
+
+```text
+Online transcription: Your Mac -> OpenAI Audio Transcriptions API
+Text rewriting:       Your Mac -> OpenAI Chat Completions API
+Local transcription:  Your Mac -> WhisperKit/CoreML on device
+```
+
+The app stores your OpenAI API key in the user's macOS Keychain.
+
+Read [docs/privacy.md](docs/privacy.md) before using the preview with sensitive content.
+
+## Project Structure
+
+```text
+BlitztextMac/
+  App/          App lifecycle and paste handling
+  Features/     Workflows, menu bar UI, settings
+  Services/     Recording, OpenAI calls, hotkeys, local storage
+  Views/        Shared SwiftUI views
+build.sh        Local build script
+docs/           Setup, privacy, roadmap, preflight, landing page notes
+```
+
+## Local Models
+
+Local transcription is available as an experimental WhisperKit/CoreML path. The app does not bundle a model; choose one in the app, click install, and then switch on **Sicherer Lokaler Modus** from the menu bar or settings.
+
+See [docs/local-models.md](docs/local-models.md).
+
+## Contributing
+
+Contributions are welcome, especially if they make the preview easier to build, understand, or fork.
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## Support And Roadmap
+
+This preview has no formal support promise. See [SUPPORT.md](SUPPORT.md) for how to ask for help without sharing secrets.
+
+The current direction is documented in [ROADMAP.md](ROADMAP.md). Maintainer-facing release checks live in [docs/open-source-preflight.md](docs/open-source-preflight.md).
+
+## License
+
+Code is released under the MIT License. See [LICENSE](LICENSE).
+
+Project names, logos, and app icons are not automatically granted as trademarks or brand assets. See [TRADEMARKS.md](TRADEMARKS.md).

ROADMAP.md

@@ -0,0 +1,31 @@
+# Roadmap
+
+This is a preview roadmap, not a promise.
+
+## Current Scope
+
+- macOS menubar app
+- local recording and hotkeys
+- direct OpenAI API calls with a user-provided API key
+- transcription, rewriting, calmer-message, and emoji workflows
+- no hosted backend
+- no other platforms
+- no packaged public release
+
+## Next Useful Work
+
+- Make first-run setup clearer.
+- Improve credential setup, validation, and recovery UX.
+- Add a small automated test layer around prompt construction and text quality filters.
+- Add provider boundaries so OpenAI and future local transcription can be swapped more cleanly.
+- Prototype local transcription with WhisperKit or whisper.cpp.
+- Reduce the Accessibility blast radius, ideally by moving synthetic paste into a smaller helper with narrower responsibilities.
+- Add stronger supply-chain checks around downloaded local speech models.
+- Add signed and notarized release builds when the project is ready for non-developer users.
+
+## Not In Scope Yet
+
+- Production support.
+- Accounts, sync, teams, or hosted infrastructure.
+- Claims that the app is offline or privacy-complete.
+- App Store distribution.

SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+Blitztext macOS Preview is experimental software.
+
+It is provided as-is, without warranty, support guarantees, or production-readiness claims.
+
+## Supported Versions
+
+Only the current `main` branch is considered for security fixes.
+
+## Reporting A Vulnerability
+
+Please do not open a public issue with sensitive security details.
+
+Use GitHub private vulnerability reporting for this repository. Maintainers should enable it before making the repository public.
+
+If private vulnerability reporting is not available yet, open a minimal public issue titled `Security contact request` without technical details.
+
+Do not include OpenAI API keys, access tokens, private recordings, or confidential transcripts in a report.
+
+Include:
+
+- what you found
+- how to reproduce it
+- what data or system access could be affected
+- your suggested fix, if you have one
+
+## Security Notes
+
+- The app sends audio and text directly to OpenAI when you use the remote workflows.
+- Your OpenAI API key is stored in the user's macOS Keychain.
+- Temporary audio files may exist briefly during processing.
+- Accessibility permission allows the app to paste text into the current app.
+- The app currently runs **without** the macOS App Sandbox. This is a deliberate trade-off for the preview: the menubar workflow needs Accessibility-based paste into arbitrary frontmost apps, system-wide hotkeys, and Application Support paths for local WhisperKit models, all of which are awkward or impossible inside a strict sandbox. Hardened Runtime is enabled, and the entitlements are limited to microphone input and outbound network access. Reintroducing the sandbox is on the roadmap once these flows are reworked.
+
+Do not use this preview for confidential or regulated data without your own review.

SUPPORT.md

@@ -0,0 +1,25 @@
+# Support
+
+Blitztext App is an experimental preview. There is no service-level agreement, paid support channel, or guarantee that issues will be fixed.
+
+## Before Asking For Help
+
+- Make sure you can build the app with `./build.sh --debug`.
+- Check that your OpenAI API key is entered in the app settings.
+- Confirm that macOS microphone permission is granted.
+- Grant Accessibility permission if you expect automatic paste into other apps.
+- Read [docs/privacy.md](docs/privacy.md) before testing with sensitive content.
+
+## Where To Ask
+
+Use GitHub Issues for reproducible bugs and focused feature ideas.
+
+Please do not post:
+
+- OpenAI API keys
+- access tokens
+- private audio recordings
+- confidential transcripts
+- screenshots that show sensitive content
+
+For security-sensitive reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.

TRADEMARKS.md

@@ -0,0 +1,7 @@
+# Trademarks And Branding
+
+The source code in this repository is licensed under the MIT License.
+
+The project name, app name, logos, icons, and visual identity are not granted as trademarks or brand assets by the MIT License.
+
+You may fork the code under the license terms. If you publish a fork as a separate app or service, use your own name, icon, and branding unless you have explicit permission.

docs/github-settings.md

@@ -0,0 +1,33 @@
+# GitHub Settings Checklist
+
+These settings are not stored in the repository. Configure them in GitHub before going public.
+
+## Security
+
+- Enable Dependabot alerts.
+- Enable secret scanning.
+- Enable push protection for supported secret types.
+- Enable private vulnerability reporting when available.
+
+## Branch Protection
+
+Protect `main`:
+
+- require pull request before merge
+- require at least one approval
+- require the CI workflow to pass
+- dismiss stale approvals when new commits are pushed
+- block force pushes
+
+## Actions
+
+- Keep default workflow permissions read-only.
+- Require approval for workflows from first-time contributors.
+- Do not add repository secrets unless they are truly needed.
+
+## Community
+
+- Keep Issues enabled for bugs and focused requests.
+- Enable Discussions only if you want a lower-friction place for questions.
+- Set repository topics after the project is public.
+- Review the GitHub community profile before sharing the repo widely.

docs/landing-page-brief.md

@@ -0,0 +1,82 @@
+# Landing Page Brief
+
+Domain: `blitztext.app`
+
+Goal: a very small landing page for an experimental open-source macOS preview.
+
+## Hero
+
+Headline:
+
+> Blitztext macOS Preview
+
+Subline:
+
+> Speak your thoughts. Turn them into text, cleaner writing, or calmer messages.
+
+Body:
+
+> An experimental open-source macOS menubar app. Not finished, not hosted, not plug-and-play. Built to learn from, fork, and improve.
+
+Primary CTA:
+
+> View on GitHub
+
+Secondary CTA:
+
+> Read setup guide
+
+Small line:
+
+> Bring your own OpenAI API key. Optional local transcription. No hosted Blitztext backend.
+
+## Sections
+
+1. What it does
+   - Dictate
+   - Improve
+   - Calm down
+   - Add emojis
+
+2. How it works
+   - Build the app locally
+   - Paste your own OpenAI API key
+   - Press a hotkey and speak
+   - Get text back on the clipboard
+
+3. Open-source preview
+   - macOS-only
+   - MIT License
+   - experimental
+   - no warranty
+   - optional local transcription with user-installed WhisperKit models
+
+4. Privacy, plainly
+   - online workflows send audio and text to OpenAI
+   - secure local mode keeps transcription on device
+   - no public Blitztext backend
+   - rewriting still uses OpenAI
+   - do your own review before sensitive use
+
+5. Roadmap
+   - easier setup
+   - signed releases
+   - local transcription experiments
+   - clearer setup and security docs
+   - community issues
+
+## Do Not Promise
+
+- offline use
+- production readiness
+- hosted service
+- free usage without API costs
+- no data leaves the device
+- guaranteed support
+- other platforms
+- bundled local models
+- local rewriting
+
+## Visual Direction
+
+Use a real macOS screenshot or short demo GIF. Keep the page calm, sparse, and honest. Avoid fake metrics, oversized SaaS claims, and corporate origin story.

docs/local-models.md

@@ -0,0 +1,72 @@
+# Local Models
+
+Blitztext can run transcription locally with WhisperKit/CoreML. The app does not bundle a speech model, but it can download the selected compatible model from Hugging Face into the local cache.
+
+## Recommended First Model
+
+Use Whisper Small for the first local test. It is multilingual, supports German, and is much lighter than the large variants.
+
+- [argmaxinc/whisperkit-coreml: openai_whisper-small_216MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-small_216MB)
+
+Local cache path:
+
+```text
+~/Library/Application Support/Blitztext/models/whisperkit/openai_whisper-small_216MB
+```
+
+## Other Compatible Models
+
+You can also install larger WhisperKit CoreML models into the same cache directory:
+
+- [openai_whisper-large-v3-v20240930_626MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-large-v3-v20240930_626MB)
+- [openai_whisper-large-v3-v20240930_turbo_632MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-large-v3-v20240930_turbo_632MB)
+
+The app detects installed model folders that contain `AudioEncoder.mlmodelc`, `MelSpectrogram.mlmodelc`, and `TextDecoder.mlmodelc`.
+
+## Install From The App
+
+Open Blitztext, go to **Settings > Anpassen**, choose a local model, and click **Installieren**. You can also switch on **Sicherer Lokaler Modus** from the main popover; if the selected model is missing, Blitztext starts the download and installs it into the local cache.
+
+After the model is installed, the Blitztext transcription workflow can run in local mode. The rewriting workflows still use OpenAI, so they are paused while secure local mode is active.
+
+## Optional Manual Install
+
+If you prefer the CLI path, install the Hugging Face CLI so the `hf` command is available:
+
+```bash
+python3 -m pip install --upgrade "huggingface_hub[cli]"
+```
+
+Create the local model cache:
+
+```bash
+mkdir -p "$HOME/Library/Application Support/Blitztext/models/whisperkit"
+```
+
+Download the recommended first model:
+
+```bash
+hf download argmaxinc/whisperkit-coreml \
+  --include 'openai_whisper-small_216MB/*' \
+  --local-dir "$HOME/Library/Application Support/Blitztext/models/whisperkit" \
+  --max-workers 4
+```
+
+Expected folder layout:
+
+```text
+~/Library/Application Support/Blitztext/models/whisperkit/
+  openai_whisper-small_216MB/
+    AudioEncoder.mlmodelc/
+    MelSpectrogram.mlmodelc/
+    TextDecoder.mlmodelc/
+```
+
+If the folder is nested differently, the app will not detect the model.
+
+## Notes
+
+- First use can be slower because the model has to load and prewarm.
+- Local transcription avoids sending audio to OpenAI for the Blitztext workflow.
+- The app currently supports local transcription only, not local rewriting.
+- Models are downloaded on demand so the repository and app package stay small and auditable.

docs/open-source-preflight.md

@@ -0,0 +1,31 @@
+# Open Source Preflight
+
+Use this checklist before making the repository public.
+
+## P0 Before Public
+
+- Run a local build with `./build.sh --debug`.
+- Run a secret scan across the working tree and commit history.
+- Confirm there are no private URLs, hosted backend credentials, internal docs, or old project references.
+- Keep the repository private until another maintainer has reviewed the first public commit.
+- Confirm the root `LICENSE`, `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `SUPPORT.md` are present.
+- Make the preview status explicit: experimental, bring your own OpenAI API key, no hosted backend, no warranty.
+- Enable GitHub private vulnerability reporting, secret scanning, and push protection before switching the repo public.
+- Enable Dependabot alerts.
+- Protect `main` with pull requests, at least one review, and required CI checks.
+- Keep GitHub Actions permissions read-only by default.
+
+## P1 Soon After Public
+
+- Enable private vulnerability reporting.
+- Decide whether Issues alone are enough or whether Discussions should be enabled for questions.
+- Add repository topics such as `macos`, `swift`, `menubar`, `speech-to-text`, and `openai`.
+- Add a lightweight release process only after the build is signed and notarized.
+- Add basic tests once provider boundaries are extracted.
+
+## P2 Later
+
+- Add CODEOWNERS if multiple maintainers become active.
+- Add local model cleanup after the in-app download/install flow.
+- Consider CodeQL once the repo has enough surface area to justify scheduled scans.
+- Add signed and notarized release artifacts for non-developer testers.

docs/privacy.md

@@ -0,0 +1,36 @@
+# Privacy Notes
+
+Blitztext macOS Preview does not include a hosted backend.
+
+When you use the online workflows, your Mac sends data directly to OpenAI:
+
+- audio recordings for transcription
+- transcribed or typed text for rewriting
+- custom terms and prompt context if you configured them
+
+When **Sicherer Lokaler Modus** is enabled and a WhisperKit/CoreML model is installed, transcription runs on your Mac and does not send audio to OpenAI. Rewriting workflows still require OpenAI and are paused while secure local mode is active.
+
+You are responsible for your OpenAI account, API usage, costs, and data handling.
+
+## Local Data
+
+The app stores:
+
+- your OpenAI API key in the user's macOS Keychain
+- workflow settings in local app support storage
+- optional WhisperKit/CoreML model folders in local app support storage
+- temporary audio files while a transcription is being processed; the app attempts to delete each recording when the workflow ends or is cancelled
+
+Workflow output may also be placed on your clipboard so it can be pasted into another app. Auto-paste marks the clipboard entry as concealed for compatible clipboard managers and attempts to restore the previous clipboard content after paste. Clipboard managers, macOS, or other apps may still observe clipboard contents while they are present.
+
+The app uses the system TLS trust store for OpenAI and Hugging Face requests. It does not currently pin certificates. A user-installed or managed root certificate can therefore affect HTTPS trust decisions on that Mac.
+
+Settings such as custom prompts, custom terms, and context are stored in local app support storage as plain JSON. Do not put secrets into those fields.
+
+## Offline Scope
+
+Only transcription can run locally. Any workflow that rewrites, improves, or transforms text still uses OpenAI.
+
+## Sensitive Content
+
+Do not use this preview with confidential, regulated, or highly sensitive content unless you have reviewed the code, your OpenAI settings, and your legal/privacy requirements.

docs/setup.md

@@ -0,0 +1,76 @@
+# Setup
+
+This guide is for people who want to build and inspect the preview themselves.
+
+## 1. Requirements
+
+- macOS 14 or newer
+- Full Xcode, with Command Line Tools installed
+- XcodeGen
+- Homebrew, if you want to install XcodeGen with `brew install xcodegen`
+- Optional for online workflows: an OpenAI API key
+- Optional for secure local transcription: a local WhisperKit/CoreML model
+
+Install XcodeGen manually if needed:
+
+```bash
+brew install xcodegen
+```
+
+## 2. Clone And Build
+
+```bash
+git clone https://github.com/cmagnussen/blitztext-app.git
+cd blitztext-app
+./build.sh --debug
+```
+
+To launch after building:
+
+```bash
+./build.sh --run
+```
+
+## 3. Configure OpenAI For Online Workflows
+
+Open the app settings and paste your own OpenAI API key if you want online transcription or rewriting workflows.
+
+The preview currently uses:
+
+- `whisper-1` for transcription
+- `gpt-4o-mini` for lightweight rewriting
+- `gpt-4o` for the calmer-message workflow
+
+You are responsible for API access, billing, and data handling in your own OpenAI account.
+
+Never commit your API key into this repository, issues, logs, or screenshots.
+
+You can skip this step if you only want to test local transcription with a local WhisperKit model.
+
+## 4. Optional Local Transcription
+
+To use secure local transcription, choose a compatible WhisperKit CoreML model in the app and click **Installieren**. Blitztext stores models in:
+
+```text
+~/Library/Application Support/Blitztext/models/whisperkit/
+```
+
+Recommended first model: `openai_whisper-small_216MB`.
+
+See [local-models.md](local-models.md) for the exact command, model links, and expected folder layout.
+
+## 5. macOS Permissions
+
+The app needs Microphone permission to record audio.
+
+For automatic paste into the previous app, grant Accessibility permission in macOS System Settings. Without it, you can still copy and paste manually.
+
+## Troubleshooting
+
+- If `xcodebuild` reports that the active developer directory is only Command Line Tools, run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`.
+- If the build cannot find XcodeGen, install it explicitly with `brew install xcodegen`.
+- If online transcription fails immediately, check whether the API key is present and valid.
+- If secure local mode is disabled, check whether a WhisperKit model is installed in the expected folder.
+- If paste does not work, check Accessibility permission.
+- If audio is missing, check Microphone permission and macOS input settings.
+- If you see OpenAI errors, verify model access and account billing.