sybl 0.1.0__tar.gz

sybl-0.1.0/.cursor/rules/maintain-agents-md.mdc

@@ -0,0 +1,34 @@
+---
+description: Keep AGENTS.md as the living source of truth; read it first and update it whenever project reality changes.
+alwaysApply: true
+---
+
+# Maintain AGENTS.md
+
+`AGENTS.md` at the repo root is the living source of truth for the sybl project
+(mission, product spec, current state, architecture decisions, structure,
+conventions).
+
+## At the start of a task
+- Read `AGENTS.md` before planning or making changes so your work aligns with
+  the current mission, decisions, and conventions.
+
+## During / after a task — update `AGENTS.md` when you:
+- Change the mission, scope, or product behavior → update the Mission / Product
+  Spec sections.
+- Advance the project phase or status → update the Current State section and
+  `docs/ROADMAP.md`.
+- Make or reverse a technical/architecture decision → append a row/note to the
+  Architecture & Tech Decisions log (append, don't erase history).
+- Add, move, or remove top-level files/directories → update the Project
+  Structure section.
+- Establish or change a convention → update the Conventions section.
+
+## Rules
+1. Bump the `Last updated` date at the top of `AGENTS.md` whenever you edit it.
+2. Append to the decision log rather than deleting prior decisions; if a
+   decision changes, add a new entry explaining the change.
+3. Keep `AGENTS.md` concise — it is a map. Put depth in `docs/`.
+4. If reality and `AGENTS.md` disagree, fix `AGENTS.md`.
+5. Before ending a turn that changed the project, verify `AGENTS.md` is still
+   accurate and update it if anything went stale.

sybl-0.1.0/.cursor/rules/no-coauthor-commits.mdc

@@ -0,0 +1,9 @@
+# No agent co-author commit trailers
+
+When creating git commits in this repository:
+
+- **Never** add `Co-authored-by:` trailers (including `Co-authored-by: Cursor <cursoragent@cursor.com>`).
+- **Never** add any Cursor, Copilot, or AI agent attribution to commit messages.
+- Keep commit messages concise and focused on the change; author attribution is handled by git config only.
+
+If staging changes for the user to commit, leave the message body free of co-author lines.

sybl-0.1.0/.githooks/commit-msg

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Reject Cursor agent co-author trailers. Enable with: git config core.hooksPath .githooks
+if grep -qi 'Co-authored-by:.*Cursor' "$1"; then
+  echo "error: commit message must not include Co-authored-by: Cursor trailers" >&2
+  exit 1
+fi

sybl-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,96 @@
+name: Bug report
+description: Something isn't working as expected
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Include `sybl doctor` output if you can.
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Windows
+        - macOS
+        - Linux
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.x"
+    validations:
+      required: true
+
+  - type: input
+    id: sybl_version
+    attributes:
+      label: sybl version
+      placeholder: "0.1.0 or git commit"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: STT provider
+      options:
+        - Groq
+        - Deepgram
+        - Other / none
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. sybl start
+        2. Hold hotkey and speak
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: sybl doctor output
+      render: shell
+      placeholder: Paste output of `sybl doctor`
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Redact API keys. Log file is under your sybl state directory.
+      render: shell
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues before opening this
+          required: true

sybl-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Suggest an idea for sybl
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Check [docs/ROADMAP.md](https://github.com/Rikhil-Nell/sybl/blob/main/docs/ROADMAP.md)
+        before filing — some items may already be planned.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What problem does this solve? Who benefits?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Primary platform
+      options:
+        - Windows
+        - macOS
+        - Linux
+        - Cross-platform
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: This aligns with sybl's BYOK, local-first mission (no hosted backend)
+          required: true
+        - label: I searched existing issues before opening this
+          required: true

sybl-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Test plan
+
+- [ ] `uv run ruff check sybl tests`
+- [ ] `uv run pytest -m "not integration" -q`
+- [ ] Updated [AGENTS.md](AGENTS.md) if behavior or architecture changed
+- [ ] No secrets or API keys in the diff
+
+## Platform notes
+
+<!-- If hotkeys, injection, or indicator code changed, describe manual Windows testing. -->
+
+- [ ] Not applicable
+- [ ] Tested manually on Windows

sybl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+        python-version: ["3.12"]
+    env:
+      NO_COLOR: "1"
+      TERM: dumb
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y portaudio19-dev xvfb
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Linux keyring backend
+        if: runner.os == 'Linux'
+        run: uv pip install keyrings.alt
+
+      - name: Lint
+        run: uv run ruff check sybl tests
+
+      - name: Unit tests (Linux)
+        if: runner.os == 'Linux'
+        env:
+          PYTHON_KEYRING_BACKEND: keyrings.alt.file.PlaintextKeyring
+        run: xvfb-run uv run pytest -m "not integration" -q --ignore=tests/test_inject.py
+
+      - name: Unit tests (Windows)
+        if: runner.os == 'Windows'
+        run: uv run pytest -m "not integration" -q

sybl-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sybl-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+
+# Logs
+*.log

sybl-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

sybl-0.1.0/AGENTS.md

@@ -0,0 +1,256 @@
+# AGENTS.md
+
+> Living source of truth for the sybl project. Read this first. Keep it current.
+> Last updated: 2026-06-28 (rebrand to sybl — package, CLI, PyPI, and paths)
+
+---
+
+## 1. Mission
+
+**sybl is an open-source, bring-your-own-key (BYOK) voice dictation tool.**
+
+Put your cursor anywhere, hit a global shortcut, speak/ramble into a lightweight
+popup, and sybl transcribes it fast and types it in for you — wherever you were
+about to type. It is the open-source answer to closed tools like Wispr Flow.
+
+The guiding principles:
+
+- **BYOK, provider-agnostic.** Users plug in whatever speech-to-text (STT)
+  credits they already have — Deepgram, AssemblyAI, Gladia, Groq (Whisper
+  large-v3), etc. No vendor lock-in, no sybl-hosted backend, no subscription.
+- **Local-first & private.** Audio goes straight from the user's machine to the
+  STT provider of their choice. sybl keeps no telemetry and stores nothing it
+  doesn't have to.
+- **Fast & invisible.** Dictation should feel instant and stay out of the way.
+- **TUI, daemon-based.** sybl runs as a background daemon. All of its UI is a
+  terminal UI (TUI): live logs, status, history, and config — nothing more.
+
+## 2. What sybl Does (Product Spec)
+
+- **Global activation.** A system-wide shortcut works regardless of focused app.
+- **Two interaction modes:**
+  - **Push-to-talk (PTT):** hold the shortcut, speak, release to finish.
+  - **Toggle / constant recording:** a double-press of the shortcut starts
+    continuous recording; press again to stop.
+- **Popup capture surface.** When activated, a small on-screen pill appears near the
+  cursor so the user knows sybl is listening (Windows tkinter overlay MVP; see
+  `docs/POPUP-SPIKE.md`).
+- **BYOK transcription.** Audio is streamed/sent to the user's selected provider
+  and transcribed quickly.
+- **Text injection.** The transcript is inserted at the current cursor location
+  in whatever app had focus when activation happened.
+- **TUI surface.** A Textual-based TUI shows live logs, current state, and a
+  scrollback history of recent transcriptions for reference.
+
+## 3. Current State
+
+> Update this section every time the project's reality changes.
+
+- **Phase:** Phase 10 complete — v0.1.0 public release on GitHub and PyPI; contributor
+  docs, CI (Windows + Ubuntu), issue/PR templates, and user docs hub shipped.
+- **Code:** `sybl/audio/` implements `AudioCaptureSession` (sounddevice callback →
+  asyncio queue, 16 kHz mono int16, resampling, dBFS peak metering, debug WAV save).
+  `sybl/providers/` implements streaming-first STT interface, `ProviderCapabilities`,
+  `resolve_provider` session-start selection, `GroqProvider` (batch), and
+  `DeepgramProvider` (WebSocket streaming + REST batch via official SDK).
+  `sybl/hotkeys/` implements `HotkeyManager`, binding parser, Windows `pynput` PTT
+  backend, and focus capture at activation. `sybl/inject/` implements `TextInjector`,
+  Windows clipboard-paste injection with focus restore and clipboard restoration.
+  `sybl/core/` has `StateMachine`, `DictationController`, `SyblDaemon`, post-processing,
+  voice commands, `TranscriptHistory`, `EventBus`, and transcribe pipeline.
+  `sybl/config/vocabulary.py` stores STT hint terms. `sybl/ipc/` implements
+  NDJSON command/event TCP servers and client. `sybl/tui/` is a Textual app (logs,
+  status, history, settings, BYOK onboarding). `sybl/indicator/` implements
+  `CaptureIndicator` (NoOp + Windows tkinter overlay near cursor with RMS level bar).
+  CLI: `sybl start`, `sybl stop`, `sybl status`, `sybl tui`, `sybl config`,
+  `sybl config vocab`, `sybl doctor`, `sybl audio`, `sybl transcribe`, `sybl hotkey test`.
+- **Stack pinned:** `typer`, `pydantic`, `platformdirs`, `keyring`, `tomli-w`,
+  `sounddevice`, `numpy`, `soundfile`, `soxr`, `groq`, `tenacity`, `deepgram-sdk`,
+  `pynput`, `textual`; dev: `ruff`, `pytest`, `pytest-asyncio`.
+- **Primary platform:** Windows first (dev machine). Code stays cross-platform
+  behind interfaces, but the core loop is proven on Windows before expanding.
+- **Open questions:** per-platform overlay beyond Windows; text-injection
+  edge cases (Wayland especially); how aggressive default post-processing should
+  be.
+
+## 4. Architecture & Tech Decisions
+
+> A decision log. Append new decisions; don't silently rewrite history.
+
+| Area | Decision | Rationale |
+|------|----------|-----------|
+| Language | Python 3.12 | Already scaffolded; first-class STT SDKs; great TUI ecosystem. |
+| Packaging / env | `uv` + `pyproject.toml` | Already in place; fast, reproducible. |
+| TUI framework | Textual (pinned) | Modern, async, rich rendering for logs/history; `sybl tui` attaches over IPC. |
+| Audio capture | `sounddevice` + **callback → queue** pattern | PortAudio bindings, NumPy-friendly; callback pushes int16 PCM to an `asyncio.Queue`; never block or process in the callback. |
+| Audio format | **16 kHz, mono, int16 PCM** | What most STT providers expect; resample in-pipeline if the device opens at 48 kHz. |
+| Daemon concurrency | **`asyncio` event loop** + dedicated audio thread | Daemon/TUI/async providers run on asyncio; sounddevice callback thread only enqueues chunks. |
+| Global hotkeys | `pynput` for **MVP**, behind `HotkeyManager` interface | Fast to ship on Windows; plan migration to a small **native helper** (e.g. Rust `global-hotkey`) if reliability stalls. Avoid the `keyboard` library (security/root issues). |
+| STT providers | Pluggable, **streaming-first** interface | Core BYOK requirement; designing for streaming up front avoids rework when batch is the easy case. |
+| Reference provider | **Deepgram** (streaming) as reference; **Groq Whisper** (batch) as early sanity check | Deepgram's streaming is fast/feature-rich and makes the cleanest reference; Groq gives the fastest first end-to-end signal as a degenerate batch case behind the same interface. |
+| Groq integration | Official **`groq` SDK** + in-memory WAV upload via `asyncio.to_thread()` | OpenAI-compatible transcriptions endpoint; default model `whisper-large-v3-turbo`; PCM→WAV matches Groq's 16 kHz mono expectation. |
+| Deepgram integration | Official **`deepgram-sdk`** — WebSocket `wss://api.deepgram.com/v1/listen` for streaming, REST `/v1/listen` for batch | Raw linear16 PCM at 16 kHz mono on websocket; `interim_results=true` for partials; `CloseStream` on end; default model `nova-3`. |
+| Process model | Background daemon + TUI client over local IPC | Daemon listens for hotkeys always; TUI attaches on demand. |
+| Daemon authority | Daemon is the **single source of truth** | Owns mic, providers, state machine, injection, config; TUI is a thin observe/command client. Config changes flow through the daemon so they persist and take effect immediately (no TUI/daemon drift). |
+| IPC shape | Simple command/response + a separate log/event stream; ring buffer for logs & history | More maintainable than sharing complex objects across processes; predictable memory; clean TUI reconnects. |
+| STT interface shape | **Async generators** yielding `TranscriptionResult` | `async def transcribe(audio: bytes \| AsyncIterable[bytes]) -> AsyncGenerator[TranscriptionResult, None]` with `text`, `is_final`, optional `confidence`. |
+| STT errors/retries | Custom exception hierarchy + **`tenacity`** | Normalize `STTError`, `STTTimeoutError`, `STTRateLimitError`; retry only transient failures. |
+| Provider selection | **`ProviderManager`** above providers | Registry + capability flags + config-driven fallback at **session start** (not mid-stream). |
+| Config validation | **Pydantic** models | Schema validation and sane defaults for provider/device settings. |
+| Text injection | **Clipboard set + simulated paste = primary**; synthetic keystrokes = labeled secondary/experimental | Paste is the most forgiving path in pure Python; restore prior clipboard after. Wispr-level reliability eventually needs **native injection** (Win `SendInput`, macOS `CGEvent`) — document limitations until then. |
+| Hotkey escape hatch | If `pynput` reliability becomes a recurring problem, introduce a small **native component** (Rust `global-hotkey` or similar) rather than fighting Python libs | Commercial tools use native code per OS; pure Python won't match Wispr Flow on hotkeys/injection long-term. |
+| Signal metering | **RMS level** for UI now; proper **VAD later** | RMS feeds the popup/TUI meter; `webrtcvad` or `silero-vad` when we need to avoid cutting off speech or trailing silence. |
+| Core concerns | State machine + post-processing pipeline are **first-class from early on** | They sit at the center of UX and the core text path; easier to refine while surrounding plumbing is still simple. |
+| Secrets | OS keyring via `sybl.secrets` | Keep API keys out of plaintext config; `sybl config set-key`. |
+| CLI | Typer subcommands | `start`, `stop`, `status`, `tui`, `config`, `doctor`, `audio`, `transcribe`, `hotkey`. |
+| Logging | File + console + ring buffer | `sybl.logging.setup_logging`; ring buffer for future TUI tail. |
+| Phase 4 hotkeys | **PTT-first** via `pynput` behind `HotkeyManager`; focus captured at **activation press** | Reliability anchor before toggle mode; HWND stored for Phase 5 injection; Windows-only MVP. |
+| Phase 5 injection | **Clipboard set + simulated Ctrl+V** via `SendInput` (ctypes); restore prior clipboard; focus restore with thread attach | Primary strategy on Windows; avoids pynput paste deadlock with hotkey listener; no new deps. |
+| Phase 5.5 post-processing | **Rule-based pipeline** (`PostProcessConfig` + ordered passes) between STT and inject | Whitespace, filler trim, capitalize on by default; auto-punctuation off; Phase 9 expands without restructuring. |
+| Phase 6 IPC | **TCP localhost NDJSON** — separate command + event ports; `daemon.json` + PID lock | Cross-platform; asyncio-native; TUI/CLI attach without shared memory. |
+| Phase 7 TUI | **Textual dashboard** — logs, status, history, settings, BYOK onboarding | All config/key writes routed through daemon IPC; keyboard-driven MVP. |
+| Phase 8 indicator | **Windows tkinter overlay** on dedicated thread; `CaptureIndicator` protocol + `NoOpIndicator` elsewhere | Stdlib, no new deps; cursor position via ctypes; show on LISTENING, RMS level bar; degrade to no-op if tk fails (`docs/POPUP-SPIKE.md`). |
+| Phase 9 vocabulary | **STT hints only** — `vocabulary.toml` + Deepgram keyterms + Groq prompt at session start | Names/jargon at transcription source; no post-STT replacement map; term list reused by future LLM pass. |
+| Phase 9 voice commands | **Final-transcript parsing** — `new line`, `period`, `comma` | No streaming/wake-word; Esc cancels before STT/inject; no scratch-that erase. |
+| Phase 10 OSS | **MIT license**, PyPI + `pipx`/`uv tool` primary install, GitHub issue/PR templates, CI on Windows+Ubuntu | Hermes-style contributor surface without a separate docs site; `docs/` hub + README landing page. |
+| Phase 10 PyPI | **`release.yml`** on GitHub Release → `uv build` → PyPI trusted publishing (OIDC) | No long-lived PyPI token in repo; maintainers configure pending publisher on PyPI. |
+| Rebrand | **sybl** everywhere — Python package `sybl/`, CLI **`sybl`**, PyPI **`sybl`**, app id `sybl` | Prior names `navi` and `sybil`/`sybil-dictation` were taken or conflicted on PyPI; `sybl` is the canonical name. |
+
+High-level component map:
+
+```
+                 +-------------------+
+  global hotkey  |   Hotkey Listener |
+  ───────────────▶  (PTT / toggle)  │
+                 +---------+---------+
+                           │ activate
+                           ▼
++-----------+      +-------+-------+      +------------------+
+|  Audio    |─────▶|  Daemon Core  |─────▶|  STT Provider    |
+|  Capture  | PCM  | (state machine)| audio|  (BYOK, pluggable)|
++-----------+      +-------+-------+      +--------+---------+
+                           │  transcript          │ text
+                           ▼                       │
+                  +--------+--------+◀─────────────+
+                  | Text Injection  |
+                  | (cursor target) |
+                  +-----------------+
+                           ▲
+         +-----------------+------------------+
+         │ IPC (logs/state/history)           │
++--------+--------+              +-----------+-----------+
+|   TUI Client    |              | Capture Indicator     |
+| (Textual app)   |              | (listening pill, Win) |
++-----------------+              +-----------------------+
+```
+
+## 5. Project Structure
+
+> Keep this in sync with the real tree as it grows.
+
+```
+sybl/
+├── AGENTS.md
+├── README.md
+├── LICENSE
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── SECURITY.md
+├── CHANGELOG.md
+├── .github/
+│   ├── ISSUE_TEMPLATE/
+│   ├── PULL_REQUEST_TEMPLATE.md
+│   └── workflows/          # ci.yml, release.yml
+├── .githooks/              # optional commit-msg hook (no Cursor co-author)
+├── docs/
+│   ├── getting-started.md
+│   ├── providers.md
+│   ├── configuration.md
+│   ├── permissions.md
+│   ├── DEVELOPMENT.md
+│   ├── DAEMON.md
+│   ├── POPUP-SPIKE.md
+│   ├── ROADMAP.md
+│   └── RESEARCH-NOTES.md
+├── main.py                # legacy redirect to CLI
+├── pyproject.toml
+├── tests/
+│   ├── conftest.py
+│   ├── test_audio.py
+│   ├── test_bindings.py
+│   ├── test_cli.py
+│   ├── test_config.py
+│   ├── test_deepgram.py
+│   ├── test_dictation.py
+│   ├── test_doctor.py
+│   ├── test_daemon_indicator.py
+│   ├── test_history.py
+│   ├── test_hotkeys.py
+│   ├── test_indicator.py
+│   ├── test_inject.py
+│   ├── test_ipc_protocol.py
+│   ├── test_ipc_server.py
+│   ├── test_logging.py
+│   ├── test_manager.py
+│   ├── test_postprocess.py
+│   ├── test_providers.py
+│   ├── test_secrets.py
+│   ├── test_single_instance.py
+│   ├── test_transcribe.py
+│   ├── test_tui_client.py
+│   ├── test_vocabulary.py
+│   ├── test_voice_commands.py
+│   └── test_provider_vocabulary.py
+└── sybl/
+    ├── __init__.py
+    ├── __main__.py
+    ├── cli/               # start, stop, status, tui, config, doctor, audio, transcribe, hotkey
+    ├── config/            # Pydantic models, paths, ConfigManager, vocabulary store
+    ├── secrets/           # keyring wrapper
+    ├── logging/           # setup + RingBufferHandler
+    ├── ipc/               # NDJSON command/event servers + client
+    ├── audio/             # capture session, devices, resample, metering
+    ├── core/              # daemon, dictation, postprocess, voice commands, transcribe
+    ├── providers/         # STT interface, capabilities, manager, Groq, Deepgram
+    ├── hotkeys/           # HotkeyManager, bindings, pynput backend, focus capture
+    ├── inject/            # TextInjector, Windows clipboard-paste injection
+    ├── indicator/         # CaptureIndicator, NoOp, Windows tkinter overlay
+    └── tui/               # Textual client (dashboard, settings, onboarding)
+```
+
+## 6. Conventions
+
+- **Python:** target 3.12, type hints everywhere, **`ruff`** for lint/format.
+- **Async:** the daemon and TUI are async-first (Textual is async); keep the
+  audio/STT pipeline non-blocking.
+- **Comments:** explain *why*, not *what*. No narration comments.
+- **Secrets:** never commit API keys; never log them. Use the keyring.
+- **Cross-platform:** Windows, macOS, and Linux are all in scope long-term, but
+  **Windows is the primary target** for the core loop first. Always isolate
+  platform-specific code (hotkeys, injection, popup) behind interfaces so other
+  platforms slot in later without touching the core.
+
+## 7. Self-Maintenance Protocol (READ THIS, AGENT)
+
+`AGENTS.md` is the project's living memory. **You are responsible for keeping it
+accurate.** After any meaningful change, update the relevant sections in the
+same task — do not defer it.
+
+Update `AGENTS.md` whenever you:
+
+- Change the mission, scope, or product behavior → update §1/§2.
+- Advance the project's phase or status → update §3 (and `docs/ROADMAP.md`).
+- Make or reverse a technical/architecture decision → append to §4.
+- Add, move, or remove top-level files/directories → update §5.
+- Establish or change a convention → update §6.
+
+Rules:
+
+1. **Bump `Last updated`** at the top whenever you edit this file.
+2. **Append, don't erase** decisions in §4 — if a decision changes, add a new
+   row/note explaining the change rather than deleting the old one.
+3. **Keep it concise.** This is a map, not a manual. Link out to `docs/` for
+   depth.
+4. **If reality and this file disagree, this file is wrong — fix it.**
+5. When you finish a unit of work, ask yourself: *"Did anything here go stale?"*
+   If yes, update it before ending your turn.

sybl-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-26
+
+First public release. sybl is a BYOK voice dictation daemon with global
+push-to-talk, STT provider plugins, clipboard-paste injection, and a Textual TUI.
+
+### Added
+
+- CLI: `sybl start`, `sybl stop`, `sybl status`, `sybl tui`, `sybl config`, `sybl doctor`, `sybl audio`, `sybl transcribe`, `sybl hotkey`
+- Config system (TOML + Pydantic) and OS keyring secret storage
+- Audio capture pipeline (16 kHz mono PCM, resampling, RMS metering, debug WAV)
+- STT providers: Groq Whisper (batch) and Deepgram (streaming + batch)
+- Global PTT hotkeys on Windows (`pynput`) with focus capture at activation
+- Clipboard-paste text injection on Windows with clipboard restore
+- Rule-based post-processing pipeline (fillers, capitalization, punctuation cleanup)
+- Daemon + TCP NDJSON IPC; Textual TUI (logs, status, history, settings, onboarding)
+- Windows listening indicator (tkinter overlay pill near cursor)
+- Custom vocabulary STT hints (`sybl config vocab`) for Deepgram keyterms and Groq prompt
+- Voice commands in final transcripts: `new line`, `period`, `comma`
+- Duplicate punctuation collapse in post-processing
+
+### Changed
+
+- **Rebrand:** project renamed from Navi to **sybl** (`sybl` CLI, PyPI package `sybl`)
+- Removed `scratch that` voice command; use **Esc** while holding the hotkey to cancel
+  before injection instead
+
+### Notes
+
+- **Windows-first:** hotkeys, injection, and the listening indicator are proven on
+  Windows. macOS/Linux backends are stubs behind interfaces.
+- Integration tests requiring a microphone or live API keys are marked `@integration`
+  and excluded from CI.
+
+[0.1.0]: https://github.com/Rikhil-Nell/sybl/releases/tag/v0.1.0

sybl-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **nrikhil@gmail.com**. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.