huske 0.1.0__tar.gz

huske-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Build artifacts
+build/
+dist/
+*.egg
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Local data
+.env
+.env.local
+.env.*
+!.env.example
+
+# Generated recordings, transcripts, logs, and model/cache data
+audio/
+transcripts/
+logs/
+models/

huske-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to huske will be documented in this file.
+
+This project uses semantic versioning after the first public release.
+
+## Unreleased
+
+- Nothing yet.
+
+## 0.1.0
+
+### Added
+
+- Initial always-on macOS terminal recorder.
+- Microphone and system audio capture.
+- Local transcription through faster-whisper.
+- Day-organized Markdown transcript output.
+- Recovery for orphaned audio chunks.
+- Rich terminal UI and setup doctor.
+- Open source project structure: license, contribution guide, code of conduct,
+  security policy, support guide, issue templates, PR template, and CI.

huske-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+huske should be a practical, respectful project for people building local-first
+audio tooling.
+
+## Expected behavior
+
+- Be direct, kind, and constructive.
+- Assume privacy-sensitive context around audio, transcripts, logs, and device
+  details.
+- Keep critique focused on code, documentation, behavior, and project outcomes.
+- Respect maintainer decisions about project scope and user safety.
+
+## Unacceptable behavior
+
+- Harassment, insults, threats, or sustained disruption.
+- Publishing another person's private information.
+- Sharing audio, transcripts, logs, screenshots, or identifiers without consent.
+- Pressuring contributors to disclose sensitive local environment details.
+- Repeatedly ignoring maintainer guidance after being asked to stop.
+
+## Enforcement
+
+Maintainers may edit or delete comments, close issues, reject contributions, or
+block participants when needed to keep the project safe and productive. Reports
+can be sent privately through the security reporting path in
+[SECURITY.md](SECURITY.md) when public discussion would expose sensitive details.

huske-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to huske
+
+Thanks for helping improve huske. This project records microphone and system
+audio, so contribution quality includes privacy hygiene as much as code quality.
+
+## Code of conduct
+
+Participating in this project means following the project
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Before opening an issue
+
+1. Search existing issues and pull requests for the same report or proposal.
+2. Run `huske doctor` and include only non-sensitive results.
+3. Check [README.md](README.md), [docs/development.md](docs/development.md),
+   and the feature specs under [specs/](specs/).
+4. Remove names, meeting details, raw transcript text, audio files, paths that
+   expose private information, and any credentials before posting.
+
+Use the issue templates when available:
+
+- Bug report: reproducible failures, crashes, bad transcripts, device problems.
+- Feature request: new behavior, platform support, workflow improvements.
+- Documentation: unclear, missing, or outdated docs.
+- Security or privacy vulnerability: follow [SECURITY.md](SECURITY.md) instead
+  of opening a public issue.
+
+## Finding work to pick up
+
+Good first issues should be small, reproducible, and covered by a focused test
+or documentation change. Useful labels for maintainers are documented in
+[docs/issue-triage.md](docs/issue-triage.md). If an issue is not clearly scoped,
+ask for clarification before starting implementation.
+
+## Development setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+For macOS capture checks, run:
+
+```bash
+huske doctor
+```
+
+For the current CI baseline, run:
+
+```bash
+pytest tests/unit
+pytest tests/integration/test_pipeline_no_whisper.py tests/integration/test_smoke.py
+```
+
+Ruff and Mypy configuration is present for local quality work, but they are not
+CI gates yet while the 0.1 codebase is being stabilized. Integration tests are
+documented in [docs/development.md](docs/development.md); some need macOS
+permissions or download a Whisper model.
+
+## Pull requests
+
+1. Open an issue first for non-trivial behavior changes.
+2. Keep PRs focused on one concern.
+3. Add or update tests when behavior changes.
+4. Update README, docs, examples, or specs when user-facing behavior changes.
+5. Do not commit generated audio, transcripts, logs, local config, model caches,
+   credentials, or screenshots containing private content.
+6. Link the relevant issue in the PR description.
+7. Fill out the PR checklist and include the exact checks you ran.
+
+Commit messages should be short and descriptive. Existing history uses a simple
+conventional style such as `feat:`, `fix:`, `docs:`, `test:`, and `chore:`.
+
+## License of contributions
+
+By submitting a contribution, you agree that your contribution is licensed under
+the same [MIT License](LICENSE) as the project.

huske-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiago Moraes
+
+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.

huske-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: huske
+Version: 0.1.0
+Summary: Always-on terminal audio recorder + local transcription (Whisper)
+Project-URL: Homepage, https://github.com/tiagomoraes/huske
+Project-URL: Repository, https://github.com/tiagomoraes/huske
+Project-URL: Issues, https://github.com/tiagomoraes/huske/issues
+Project-URL: Changelog, https://github.com/tiagomoraes/huske/blob/develop/CHANGELOG.md
+Author: Tiago Moraes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,terminal,transcription,tui,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Requires-Python: <3.14,>=3.11
+Requires-Dist: faster-whisper>=1.0.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyobjc-framework-coremedia>=10; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-screencapturekit>=10; sys_platform == 'darwin'
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: sounddevice>=0.4.6
+Requires-Dist: soundfile>=0.12.1
+Requires-Dist: structlog>=24.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# huske
+
+[![CI](https://github.com/tiagomoraes/huske/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/tiagomoraes/huske/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> *huske* — Norwegian for "to remember"
+
+A terminal app that runs in the background, continuously records your microphone
+plus your computer's system audio, and transcribes the audio locally with
+[faster-whisper](https://github.com/SYSTRAN/faster-whisper) — producing a
+day-organized, LLM-friendly knowledge base of everything that was said on your
+machine throughout the day.
+
+Point Claude Code (or any other LLM agent) at `~/huske/transcripts/` and ask
+it about your day.
+
+```text
+~/huske/transcripts/
+├── 2026-05-07/
+│   ├── 091500_8a3f2c19_001.md
+│   ├── 093000_8a3f2c19_002.md
+│   └── 094500_8a3f2c19_003.md
+└── README.md
+```
+
+## Features
+
+- **Continuous capture** — mic (sounddevice) + system audio (Apple ScreenCaptureKit),
+  mixed in software, no gaps at chunk boundaries.
+- **No drivers, no Audio MIDI Setup** — system audio comes through Apple's
+  modern ScreenCaptureKit framework. Just grant Screen Recording permission once.
+- **Local transcription** — `faster-whisper`, default `base` model. Audio never
+  leaves your machine.
+- **Configurable chunk size** — default 15 minutes, anything from 6 s to 60 min.
+- **Resilient** — graceful stop finalizes the partial chunk; SIGKILL + restart
+  auto-recovers orphaned audio.
+- **Pretty terminal UI** — Rich Live panel with countdown, mic + system level
+  meters, queue depth, last-saved transcript, rolling event log.
+- **LLM-ready output** — every transcript is a single Markdown file with full
+  YAML frontmatter; the directory layout is documented in
+  `~/huske/transcripts/README.md` (auto-generated).
+
+## Requirements
+
+- macOS 13 (Ventura) or newer. Apple Silicon is the primary target.
+- Python 3.11, 3.12, or 3.13.
+
+## Quickstart
+
+```bash
+# 1. Install
+uv tool install huske
+
+# pipx works too:
+# pipx install huske
+
+# 2. Validate setup (will prompt for Screen Recording permission on first run)
+huske doctor
+
+# 3. Record (Ctrl+C to stop)
+huske run
+
+# 4. Reclaim orphans from a prior crash without recording
+huske recover
+```
+
+On first launch macOS will prompt you to grant **Screen Recording** permission
+to your Python interpreter — that's what ScreenCaptureKit needs to capture
+system audio. After approving once, it's silent forever.
+
+For prerelease builds or exact GitHub tags, install directly from the repository:
+
+```bash
+uv tool install "git+https://github.com/tiagomoraes/huske.git@v0.1.0"
+```
+
+See [quickstart.md](specs/001-huske-recorder/quickstart.md) for the full setup.
+
+## Privacy and consent
+
+huske is local-first: audio capture and transcription run on your machine, and
+the app writes transcripts to your configured filesystem path. That does not
+make the data low-risk. Recordings, transcripts, logs, filenames, and device
+metadata can contain private or legally sensitive information.
+
+- Get consent before recording other people or regulated conversations.
+- Do not commit generated audio, transcripts, logs, local configs, model caches,
+  or screenshots containing private content.
+- Redact `huske doctor` output before sharing it publicly.
+- Report security or privacy vulnerabilities privately through
+  [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+- [Development](docs/development.md) — local setup, checks, and test strategy.
+- [Contributing](CONTRIBUTING.md) — how to open issues and pull requests.
+- [Issue triage](docs/issue-triage.md) — labels and maintainer workflow.
+- [Release checklist](docs/releasing.md) — release preparation notes.
+- [Spec](specs/001-huske-recorder/spec.md) — what huske does and why.
+- [Plan](specs/001-huske-recorder/plan.md) — technical context and architecture.
+- [CLI contract](specs/001-huske-recorder/contracts/cli.md) — flags, exit codes.
+- [Transcript format contract](specs/001-huske-recorder/contracts/transcript-format.md) — the LLM-consumer interface.
+- [Quickstart](specs/001-huske-recorder/quickstart.md) — end-to-end setup.
+
+## Community
+
+- Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Use issue templates for bugs, features, and documentation reports.
+- Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) and include
+  the exact checks you ran.
+- For help, see [SUPPORT.md](SUPPORT.md).
+
+## License
+
+huske is released under the [MIT License](LICENSE). Third-party notices are in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

huske-0.1.0/README.md

@@ -0,0 +1,116 @@
+# huske
+
+[![CI](https://github.com/tiagomoraes/huske/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/tiagomoraes/huske/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> *huske* — Norwegian for "to remember"
+
+A terminal app that runs in the background, continuously records your microphone
+plus your computer's system audio, and transcribes the audio locally with
+[faster-whisper](https://github.com/SYSTRAN/faster-whisper) — producing a
+day-organized, LLM-friendly knowledge base of everything that was said on your
+machine throughout the day.
+
+Point Claude Code (or any other LLM agent) at `~/huske/transcripts/` and ask
+it about your day.
+
+```text
+~/huske/transcripts/
+├── 2026-05-07/
+│   ├── 091500_8a3f2c19_001.md
+│   ├── 093000_8a3f2c19_002.md
+│   └── 094500_8a3f2c19_003.md
+└── README.md
+```
+
+## Features
+
+- **Continuous capture** — mic (sounddevice) + system audio (Apple ScreenCaptureKit),
+  mixed in software, no gaps at chunk boundaries.
+- **No drivers, no Audio MIDI Setup** — system audio comes through Apple's
+  modern ScreenCaptureKit framework. Just grant Screen Recording permission once.
+- **Local transcription** — `faster-whisper`, default `base` model. Audio never
+  leaves your machine.
+- **Configurable chunk size** — default 15 minutes, anything from 6 s to 60 min.
+- **Resilient** — graceful stop finalizes the partial chunk; SIGKILL + restart
+  auto-recovers orphaned audio.
+- **Pretty terminal UI** — Rich Live panel with countdown, mic + system level
+  meters, queue depth, last-saved transcript, rolling event log.
+- **LLM-ready output** — every transcript is a single Markdown file with full
+  YAML frontmatter; the directory layout is documented in
+  `~/huske/transcripts/README.md` (auto-generated).
+
+## Requirements
+
+- macOS 13 (Ventura) or newer. Apple Silicon is the primary target.
+- Python 3.11, 3.12, or 3.13.
+
+## Quickstart
+
+```bash
+# 1. Install
+uv tool install huske
+
+# pipx works too:
+# pipx install huske
+
+# 2. Validate setup (will prompt for Screen Recording permission on first run)
+huske doctor
+
+# 3. Record (Ctrl+C to stop)
+huske run
+
+# 4. Reclaim orphans from a prior crash without recording
+huske recover
+```
+
+On first launch macOS will prompt you to grant **Screen Recording** permission
+to your Python interpreter — that's what ScreenCaptureKit needs to capture
+system audio. After approving once, it's silent forever.
+
+For prerelease builds or exact GitHub tags, install directly from the repository:
+
+```bash
+uv tool install "git+https://github.com/tiagomoraes/huske.git@v0.1.0"
+```
+
+See [quickstart.md](specs/001-huske-recorder/quickstart.md) for the full setup.
+
+## Privacy and consent
+
+huske is local-first: audio capture and transcription run on your machine, and
+the app writes transcripts to your configured filesystem path. That does not
+make the data low-risk. Recordings, transcripts, logs, filenames, and device
+metadata can contain private or legally sensitive information.
+
+- Get consent before recording other people or regulated conversations.
+- Do not commit generated audio, transcripts, logs, local configs, model caches,
+  or screenshots containing private content.
+- Redact `huske doctor` output before sharing it publicly.
+- Report security or privacy vulnerabilities privately through
+  [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+- [Development](docs/development.md) — local setup, checks, and test strategy.
+- [Contributing](CONTRIBUTING.md) — how to open issues and pull requests.
+- [Issue triage](docs/issue-triage.md) — labels and maintainer workflow.
+- [Release checklist](docs/releasing.md) — release preparation notes.
+- [Spec](specs/001-huske-recorder/spec.md) — what huske does and why.
+- [Plan](specs/001-huske-recorder/plan.md) — technical context and architecture.
+- [CLI contract](specs/001-huske-recorder/contracts/cli.md) — flags, exit codes.
+- [Transcript format contract](specs/001-huske-recorder/contracts/transcript-format.md) — the LLM-consumer interface.
+- [Quickstart](specs/001-huske-recorder/quickstart.md) — end-to-end setup.
+
+## Community
+
+- Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Use issue templates for bugs, features, and documentation reports.
+- Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) and include
+  the exact checks you ran.
+- For help, see [SUPPORT.md](SUPPORT.md).
+
+## License
+
+huske is released under the [MIT License](LICENSE). Third-party notices are in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

huske-0.1.0/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+huske is pre-1.0 software. Security and privacy fixes are handled on the
+`develop` branch and released with the next tagged version when releases begin.
+
+## Reporting a vulnerability
+
+Do not open a public issue for vulnerabilities or privacy-sensitive reports.
+Use GitHub private vulnerability reporting when available:
+
+<https://github.com/tiagomoraes/huske/security/advisories/new>
+
+If private reporting is unavailable, open a minimal public issue asking for a
+private maintainer contact without including exploit details, audio, transcripts,
+logs, credentials, or private paths.
+
+Useful reports include:
+
+- A concise description of the risk.
+- Affected version or commit.
+- Reproduction steps using synthetic or redacted data.
+- Expected impact.
+- Any suggested mitigation.
+
+## Privacy-sensitive data
+
+huske can create audio chunks, transcripts, logs, and local configuration that
+may contain private information. Never attach raw recordings, real transcripts,
+or personal logs to public issues or pull requests.

huske-0.1.0/SUPPORT.md

@@ -0,0 +1,22 @@
+# Support
+
+huske is maintained as an open source project with best-effort support.
+
+## Where to ask
+
+- Bugs: open a bug report with the issue template.
+- Feature ideas: open a feature request and describe the workflow it enables.
+- Documentation gaps: open a documentation issue or a focused PR.
+- Security or privacy vulnerabilities: follow [SECURITY.md](SECURITY.md).
+
+## What to include
+
+- `huske --version`
+- macOS version and hardware class
+- Python version
+- `huske doctor` output with private details removed
+- The exact command you ran
+- Minimal reproduction steps using synthetic or redacted data
+
+Do not share audio files, real transcripts, private logs, credentials, meeting
+names, participant names, customer data, or screenshots with private content.

huske-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+This repository includes project scaffolding generated from
+[GitHub Spec Kit](https://github.com/github/spec-kit), primarily under
+`.specify/` and `.claude/`. GitHub Spec Kit is licensed under the MIT License.
+
+## GitHub Spec Kit
+
+MIT License
+
+Copyright GitHub, Inc.
+
+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.

huske-0.1.0/docs/development.md

@@ -0,0 +1,78 @@
+# Development
+
+huske is a Python CLI/TUI application for macOS audio capture and local
+transcription. Most core behavior is testable without real devices; device and
+Whisper checks are isolated in integration tests.
+
+## Local setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+On macOS, grant Screen Recording permission to the Python interpreter before
+running real system-audio capture. `huske doctor` validates the local setup.
+
+## Common commands
+
+```bash
+huske --help
+huske doctor
+huske run
+huske recover
+```
+
+## Checks
+
+Run the current CI baseline before opening a PR:
+
+```bash
+pytest tests/unit
+pytest tests/integration/test_pipeline_no_whisper.py tests/integration/test_smoke.py
+```
+
+Additional local quality checks:
+
+```bash
+ruff check .
+mypy huske
+```
+
+Ruff and Mypy are useful while changing Python code, but they are not required
+CI gates yet because the 0.1 branch still needs a dedicated lint/type baseline
+cleanup.
+
+Optional integration checks:
+
+```bash
+pytest tests/integration/test_system_audio.py
+pytest tests/integration/test_real_whisper.py
+```
+
+`test_system_audio.py` requires macOS Screen Recording permission.
+`test_real_whisper.py` downloads and runs the `tiny` faster-whisper model.
+
+## Project layout
+
+```text
+huske/
+  capture/       microphone and system-audio capture
+  chunker/       WAV chunk rotation
+  recovery/      orphaned audio recovery
+  transcribe/    worker process and transcript writing
+  ui/            Rich live terminal UI
+specs/           feature specs, contracts, and planning notes
+tests/           unit and integration tests
+examples/        example user configuration
+```
+
+## Privacy rules for development
+
+- Use synthetic audio in tests and examples.
+- Do not commit generated recordings, transcripts, logs, local configs, model
+  caches, or screenshots containing private content.
+- Redact paths and device names when they reveal private information.
+- Keep reproduction cases minimal and deterministic.

huske-0.1.0/docs/issue-triage.md

@@ -0,0 +1,45 @@
+# Issue Triage
+
+This guide keeps issues actionable once the project is public.
+
+## Labels
+
+- `bug`: confirmed or likely defect.
+- `feature`: new or changed behavior.
+- `docs`: documentation-only work.
+- `privacy`: behavior involving audio, transcripts, logs, consent, or local data.
+- `good first issue`: small, well-scoped, low-context task.
+- `help wanted`: scoped work where outside contribution is welcome.
+- `needs reproduction`: report needs a minimal repro.
+- `needs decision`: maintainer needs to choose product or architecture direction.
+- `blocked`: cannot progress until an external condition changes.
+
+## Bug reports
+
+A bug is actionable when it has:
+
+- Version or commit.
+- Platform and Python version.
+- Command or workflow that failed.
+- Expected behavior.
+- Actual behavior.
+- Minimal reproduction with synthetic or redacted data.
+
+If a report depends on private audio or transcripts, ask for a synthetic repro
+instead of requesting the private material.
+
+## Feature requests
+
+A feature request is actionable when it describes:
+
+- The workflow or user problem.
+- Why existing behavior is insufficient.
+- Proposed behavior.
+- Privacy or consent implications.
+- Acceptance criteria or examples.
+
+## Closing issues
+
+Close issues that are duplicates, unsupported by a reproduction after follow-up,
+outside project scope, or unsafe to handle publicly. Link to the relevant issue,
+PR, or documentation when closing.