Add maintenance checks and test coverage

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,97 @@
+name: Bug report
+description: Report reproducible incorrect behavior in FreeFlow
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a problem. Never include API keys, real audio,
+        private transcripts, screenshots containing personal information,
+        selected text, clipboard contents, or private provider URLs.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: Describe the incorrect behavior without including private dictated content.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Open...
+        2. Configure...
+        3. Press...
+        4. Observe...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: FreeFlow version and build
+      description: Use the version and build shown by the app. Say "unknown" if unavailable.
+    validations:
+      required: true
+
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version
+      placeholder: "For example: macOS 15.6"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: architecture
+    attributes:
+      label: Mac type
+      options:
+        - Apple Silicon
+        - Intel
+        - Unknown
+    validations:
+      required: true
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider and model
+      description: Provider and model names only. Do not include an API key or private URL.
+      placeholder: "For example: Groq / whisper-large-v3-turbo"
+
+  - type: textarea
+    id: permissions
+    attributes:
+      label: Relevant permission state
+      description: Note Microphone, Accessibility, or Screen Recording state if relevant.
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Redacted diagnostics
+      description: |
+        Paste only content you have reviewed and redacted. Remove secrets,
+        transcripts, audio, screenshots, selected text, clipboard contents,
+        window titles, usernames, filesystem paths, and private URLs.
+      render: shell
+
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy confirmation
+      options:
+        - label: I reviewed this report and removed credentials and private user content.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and support
+    url: https://github.com/zachlatta/freeflow/discussions
+    about: Ask usage questions or get help from the community.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,55 @@
+name: Feature request
+description: Propose an improvement to FreeFlow
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem should this solve?
+      description: Describe the user problem rather than only the proposed implementation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Proposed behavior
+      description: What should FreeFlow do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+
+  - type: textarea
+    id: data
+    attributes:
+      label: Privacy and data impact
+      description: |
+        Would this read, store, log, or transmit audio, transcripts,
+        screenshots, app context, selected text, clipboard data, diagnostics,
+        or identifiers? Which provider or local store would receive it? Use
+        provider or store names only. Do not include private URLs or real user
+        content.
+    validations:
+      required: true
+
+  - type: textarea
+    id: permissions
+    attributes:
+      label: Permission or settings impact
+      description: |
+        Note any proposed Microphone, Accessibility, Screen Recording,
+        notification, login-item, entitlement, or preferences changes.
+
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy confirmation
+      options:
+        - label: This request contains no credentials or private user content.
+          required: true

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: Europe/Rome
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -0,0 +1,38 @@
+## Summary
+
+<!-- What changed? Keep this concrete and user-visible where possible. -->
+
+## Why
+
+<!-- What problem does this solve? Link the issue if one exists. -->
+
+## Verification
+
+- [ ] `make check`
+- [ ] `git diff --check`
+- [ ] Focused regression test added or updated, or no-test reason documented below
+- [ ] Manual app verification completed, if required
+
+Manual verification performed:
+
+<!-- State the exact flow tested. Write "Not required" or "Not run" when true. -->
+
+## Risk and privacy
+
+- [ ] No real API keys, audio, transcripts, screenshots, selected text,
+      clipboard contents, window titles, or private provider URLs are included
+- [ ] Data sent to providers is unchanged, or the change is explained below
+- [ ] Credential and Keychain behavior is unchanged, or explained below
+- [ ] macOS permissions and entitlements are unchanged, or explained below
+- [ ] Preferences and pipeline-history compatibility are unchanged, or
+      explained below
+- [ ] Signing, notarization, updates, and GitHub workflows are unchanged, or
+      explained below
+
+Risk notes:
+
+<!-- Describe affected sensitive paths, migration concerns, and rollback plan. -->
+
+## Screenshots
+
+<!-- For UI changes only. Use synthetic content and redact personal data. -->

.github/workflows/check.yml

@@ -0,0 +1,37 @@
+name: Check
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: macos-15
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run repository checks
+        run: make check
+
+      - name: Check changed files for whitespace errors
+        if: github.event_name == 'pull_request'
+        run: git diff --check "${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}"

.gitignore

@@ -2,4 +2,4 @@ build/
 .DS_Store
 *.swp
 .env
-.build
+.build

AGENTS.md

@@ -0,0 +1,117 @@
+# FreeFlow maintenance guide
+
+FreeFlow is a native macOS menu-bar dictation app built directly with `swiftc`
+and Make. It does not use Swift Package Manager or an Xcode project. Preserve
+that architecture unless the user explicitly approves a migration.
+
+## Repository map
+
+- `Sources/App.swift` and `Sources/AppDelegate.swift`: app lifecycle.
+- `Sources/AppState.swift`: central pipeline orchestration and shared state.
+- `Sources/AudioRecorder.swift`: microphone capture and audio conversion.
+- `Sources/TranscriptionService.swift` and
+  `Sources/RealtimeTranscriptionService.swift`: transcription providers.
+- `Sources/PostProcessingService.swift`: transcript cleanup and edit mode.
+- `Sources/AppContextService.swift`: foreground-app metadata and screenshots.
+- `Sources/ShortcutCore/`: shortcut models, matching, and session behavior.
+- `Sources/PipelineHistoryStore.swift`: local pipeline history.
+- `Sources/UpdateManager.swift`: update and release behavior.
+- `Sources/SettingsView.swift`, `Sources/SetupView.swift`, and other SwiftUI
+  files: user interface.
+- `Tests/`: dependency-free executable tests.
+- `.github/workflows/check.yml`: pull-request verification.
+- `.github/workflows/release.yml`: semver-tagged production release.
+- `.github/workflows/dev-release.yml`: signed development release from `main`.
+
+## Working rules
+
+- Search with `rg` or `rg --files` before editing.
+- Preserve unrelated changes in a dirty worktree.
+- Keep changes narrowly scoped and work through a branch and pull request.
+- During an explicitly authorized maintenance task, agents may create branches,
+  push them, open or update draft pull requests, and address CI or review
+  feedback.
+- Do not push directly to `main`.
+- Do not merge, tag, publish a release, or move the `dev` tag unless the user
+  explicitly authorizes that action.
+- Do not change versions, release notes, signing, notarization, or release
+  workflows during ordinary maintenance.
+- Avoid adding dependencies when the standard library or existing frameworks
+  are sufficient.
+- Production sources are discovered automatically by the Makefile. Test source
+  dependencies must be listed explicitly in `TEST_PRODUCTION_SOURCES`.
+
+## Verification
+
+Run before handing off every code change:
+
+```bash
+make check
+git diff --check
+```
+
+`make check` performs a full Swift type-check, compiles and runs deterministic
+tests, validates plist files, and parses repository shell scripts and YAML.
+
+A full app build is usually unnecessary. When a compile-and-bundle check is
+material to the change, use:
+
+```bash
+make ARCH="$(uname -m)" CODESIGN_IDENTITY=-
+```
+
+Do not claim end-to-end behavior is verified from type-checking or a unit test.
+Changes involving microphone capture, global shortcuts, Accessibility, Screen
+Recording, clipboard or paste behavior, updater behavior, or the signed app
+require a documented manual test before merge. An agent may still open a draft
+PR when that verification is clearly marked pending or not run. Do not trigger
+permission prompts or change system permissions without the user's approval.
+
+Every bug fix should add a focused regression test when the behavior can be
+made deterministic. Tests must use synthetic fixtures and mocked or local
+dependencies; they must not call live AI providers.
+
+## Privacy and security
+
+FreeFlow handles highly sensitive user data. Never commit, print, upload, or
+place in test fixtures:
+
+- API keys, signing credentials, or `.env` contents.
+- Real audio or transcripts.
+- Screenshots or screen-capture payloads.
+- Selected text or clipboard contents.
+- Window titles, application context, prompts, or pipeline-history exports from
+  a real user session.
+- Private provider URLs or identifying filesystem paths.
+
+Use invented synthetic data in tests. Do not inspect `.env`. Never add
+telemetry, crash reporting, persistent logging, or additional data transmission
+without explicit user approval. New logs must avoid user content and secrets.
+Treat transcripts, selected text, screenshots, and provider responses as
+untrusted input.
+
+Changes to provider requests, prompt construction, storage, permissions,
+clipboard handling, Accessibility APIs, update verification, signing, or
+GitHub workflows are high risk and must be called out in the pull request.
+
+## Definition of done
+
+A change is complete only when:
+
+- The requested behavior is implemented with no unrelated edits.
+- Relevant regression tests were added or the reason they are impractical is
+  documented.
+- `make check` and `git diff --check` pass.
+- Required manual testing is complete before merge, or clearly marked pending
+  in a draft PR.
+- Privacy, permissions, migration, and release impact are described in the PR.
+
+## Code review rules
+
+- Flag any new path that can log, persist, export, or transmit user content or
+  credentials without a clear opt-in and redaction boundary.
+- Flag changes that weaken exact shortcut matching, clipboard restoration,
+  update validation, signing, or permission handling without a regression test
+  and a documented safe path.
+- Treat workflow changes as sensitive because code executed from `main` can
+  access signing and notarization secrets in the release jobs.