Refactor settings, enhance pipelines, and improve user experience

.env.debug.example

@@ -77,34 +77,34 @@ AI_FORMATTING_ENABLED=1
 # AI_PROVIDER=harmony            # legacy (harmony|ollama)
 # AI_MAX_TOKENS=0                # 0 = no limit
 # AI_ASSISTIVE_MAX_TOKENS=0       # 0 = no limit
-TRANSCRIPT_SEND_MODE=end_of_utterance   # end_of_utterance | streaming
+
+# end_of_utterance | streaming:
+TRANSCRIPT_SEND_MODE=end_of_utterance
 
 # Retry policy for AI calls
 # CODESCRIBE_AI_MAX_RETRIES=2
 # CODESCRIBE_AI_RETRY_DELAY_MS=500
 # CODESCRIBE_AI_ATTEMPT_TIMEOUT_MS=5000
+# CODESCRIBE_AI_OLLAMA_ATTEMPT_TIMEOUT_MS=5000
 
 # =============================================================================
 # STREAMING / CHUNKING / BUFFERED MODE (IMPORTANT)
 # =============================================================================
-CODESCRIBE_STREAM_CHUNK_SEC=15.0       # Chunk size in seconds (0.5..30)
+CODESCRIBE_STREAM_CHUNK_SEC=4.0        # Chunk size in seconds (0.5..30)
 CODESCRIBE_STREAM_OVERLAP_RATIO=0.25   # Overlap ratio (0.05..0.8) of chunk size
 CODESCRIBE_BUFFERED_STREAM=1           # 1 enables VAD buffered mode (default)
-CODESCRIBE_BUFFER_DELAY_MS=3000        # Delay before emitting buffered text
-CODESCRIBE_TYPING_CPS=30               # Emission speed in buffered mode
+# CODESCRIBE_EVENT_PIPELINE=0          # 1 enables event-based pipeline (experimental)
+CODESCRIBE_BUFFER_DELAY_MS=1800        # Delay before emitting buffered text
+CODESCRIBE_TYPING_CPS=36               # Emission speed in buffered mode
 
 # VAD for buffered mode (Silero neural network)
-CODESCRIBE_VAD_THRESHOLD=0.5
-CODESCRIBE_VAD_MIN_SPEECH_SEC=0.1
-CODESCRIBE_VAD_MAX_SILENCE_SEC=1.2
-CODESCRIBE_VAD_MAX_UTTERANCE_SEC=60
-CODESCRIBE_VAD_PRE_ROLL_SEC=0.3
+# VAD internals are hardcoded in core/vad/config.rs (Silero defaults).
 
 # =============================================================================
 # STREAM POSTPROCESS (REPETITION / GATING)
 # =============================================================================
-# CODESCRIBE_STREAM_SIMILARITY=0.90    # similarity threshold
-# CODESCRIBE_STREAM_NOVELTY=0.20       # novelty threshold
+# CODESCRIBE_STREAM_SIMILARITY=0.93    # similarity threshold
+# CODESCRIBE_STREAM_NOVELTY=0.12       # novelty threshold
 # CODESCRIBE_STREAM_DISABLE_EMBEDDINGS=0
 
 # =============================================================================
@@ -131,7 +131,7 @@ HOLD_START_DELAY_MS=800
 # UI / OVERLAYS / FEEDBACK
 # =============================================================================
 SHOW_TRAY_GLYPH=1
-HOLD_INDICATOR=1               # bool (legacy string values ignored)
+HOLD_INDICATOR=1# bool (legacy string values ignored)
 HOLD_BADGE_SIZE=12
 HOLD_BADGE_OFFSET_X=10
 HOLD_BADGE_OFFSET_Y=-10
@@ -158,7 +158,6 @@ DUMP_AUDIO_LOGS=1
 # =============================================================================
 # QUALITY LOOP / REPORTING
 # =============================================================================
-# QUALITY_DEBUG_MODE=1
 # CODESCRIBE_QUALITY_DISABLE_CLOUD=1
 
 # =============================================================================

.env.example

@@ -1,43 +1,172 @@
-# CodeScribe .env (minimal + recommended)
-# Source of truth: docs/env.md
+# CodeScribe .env (power-user overrides)
+# Priority: env vars > ~/.codescribe/.env > settings.json
 # Copy: cp .env.example ~/.codescribe/.env
 
 # =============================================================================
-# LOCAL EMBEDDED (RECOMMENDED)
+# CORE STT (LOCAL BY DEFAULT)
 # =============================================================================
 USE_LOCAL_STT=1
-WHISPER_LANGUAGE=pl
 LOCAL_MODEL=whisper-large-v3-turbo-mlx-q8
+# WHISPER_LANGUAGE=pl
+# CODESCRIBE_WHISPER_INITIAL_PROMPT=CodeScribe, LibraxisAI, Docker, GitHub
+# WHISPER_INITIAL_PROMPT=...   # legacy alias
+# CODESCRIBE_MODEL_PATH=/path/to/whisper/model  # dev override
 
 # =============================================================================
-# AI FORMATTING (OPTIONAL)
+# CLOUD STT (OPTIONAL)
 # =============================================================================
-# AI_FORMATTING_ENABLED=1
+# USE_LOCAL_STT=0
+# STT_ENDPOINT=https://api.libraxis.cloud/v1/audio/transcriptions
+# STT_API_KEY=...
+# CODESCRIBE_LOOP_USE_CLOUD_STT=1   # quality loop only
+
+# =============================================================================
+# HOTKEYS
+# =============================================================================
+HOLD_MODS=fn
+HOLD_EXCLUSIVE=1
+TOGGLE_TRIGGER=double_option
+HOLD_START_DELAY_MS=800
+DOUBLE_TAP_INTERVAL_MS=200
+TOGGLE_SILENCE_SEC=5.0
+# HOTKEY_DOUBLE_TAP_LEFT=0   # legacy (auto-migrated to TOGGLE_TRIGGER)
+# HOTKEY_DOUBLE_TAP_RIGHT=0  # legacy (auto-migrated to TOGGLE_TRIGGER)
+
+# =============================================================================
+# OVERLAY / UI
+# =============================================================================
+OVERLAY_POSITION_MODE=snapped_top_right
+# OVERLAY_CUSTOM_X=0
+# OVERLAY_CUSTOM_Y=0
+SHOW_TRAY_GLYPH=1
+SHOW_DOCK_ICON=1
+HOLD_INDICATOR=1
+HOLD_BADGE_SIZE=8
+HOLD_BADGE_OFFSET_X=10
+HOLD_BADGE_OFFSET_Y=-10
+
+# =============================================================================
+# AUDIO + SOUND
+# =============================================================================
+AUTO_SILENCE=0
+BEEP_ON_START=1
+SOUND_NAME=Tink
+SOUND_VOLUME=0.25
+# AUDIO_INPUT_DEVICE=Built-in Microphone
+
+# =============================================================================
+# CLIPBOARD + HISTORY
+# =============================================================================
+RESTORE_CLIPBOARD=1
+RESTORE_CLIPBOARD_DELAY_MS=1000
+HISTORY_ENABLED=1
+DUMP_AUDIO_LOGS=1
+
+# =============================================================================
+# QUICK NOTES
+# =============================================================================
+QUICK_NOTES_ENABLED=0
+QUICK_NOTES_SAVE_ONLY=0
+# CODESCRIBE_NOTES_DIR=~/Git/vista/notes
+
+# =============================================================================
+# AI FORMATTING / ASSISTIVE
+# =============================================================================
+AI_FORMATTING_ENABLED=1
+TRANSCRIPT_SEND_MODE=streaming   # streaming | full
+# AI_MAX_TOKENS=1200
+# AI_ASSISTIVE_MAX_TOKENS=2000
+
+# Shared LLM defaults
 # LLM_ENDPOINT=https://api.openai.com/v1/responses
 # LLM_MODEL=gpt-4.1-mini
 # LLM_API_KEY=sk-...
+# LLM_TEMPERATURE=0.2
+LLM_USE_STREAMING=1
 
-# Formatting overrides (optional)
-# LLM_FORMATTING_ENDPOINT=
-# LLM_FORMATTING_MODEL=
-# LLM_FORMATTING_API_KEY=
+# Retry/timeout policy
+# CODESCRIBE_AI_MAX_RETRIES=3
+# CODESCRIBE_AI_RETRY_DELAY_MS=2000
+# CODESCRIBE_AI_ATTEMPT_TIMEOUT_MS=30000
+# CODESCRIBE_AI_OLLAMA_ATTEMPT_TIMEOUT_MS=5000
+# CODESCRIBE_AI_INTER_CHUNK_TIMEOUT_MS=30000
+# CODESCRIBE_AI_CLIENT_TIMEOUT_MS=90000
+# CODESCRIBE_AI_CONNECT_TIMEOUT_MS=5000
+# CODESCRIBE_AI_POOL_IDLE_TIMEOUT_MS=90000
+# CODESCRIBE_AI_TCP_KEEPALIVE_MS=30000
 
-# Assistive overrides (optional)
-# LLM_ASSISTIVE_ENDPOINT=
-# LLM_ASSISTIVE_MODEL=
+# Assistive overrides
+# LLM_ASSISTIVE_ENDPOINT=https://api.openai.com/v1/responses
+# LLM_ASSISTIVE_MODEL=gpt-5.2
 # LLM_ASSISTIVE_API_KEY=
+# LLM_ASSISTIVE_TEMPERATURE=0.3
+
+# Formatting overrides
+# LLM_FORMATTING_ENDPOINT=http://localhost:11434/v1/responses
+# LLM_FORMATTING_MODEL=llama3.2
+# LLM_FORMATTING_API_KEY=
+# LLM_FORMATTING_TEMPERATURE=0.1
 
 # =============================================================================
-# CLOUD STT (OPTIONAL, CLOUD-ONLY)
+# ASSISTIVE CONTEXT CAPTURE
 # =============================================================================
-# USE_LOCAL_STT=0
-# STT_ENDPOINT=https://api.libraxis.cloud/v1/audio/transcriptions
-# STT_API_KEY=...
+# ASSISTIVE_CONTEXT_MAX_CHARS=20000
+# ASSISTIVE_CONTEXT_COPY_DELAY_MS=150
+
+# =============================================================================
+# ATTACHMENTS / OCR
+# =============================================================================
+# CODESCRIBE_ATTACH_PDF_OCR=1
+# CODESCRIBE_ATTACH_PDF_OCR_LANG=pol+eng
+# CODESCRIBE_ATTACH_PDF_PAGES=3
+# CODESCRIBE_DRAWER_INCLUDE_LEGACY=0
+
+# =============================================================================
+# STREAMING / POSTPROCESS
+# =============================================================================
+# Buffered (magic) tuning
+# CODESCRIBE_BUFFERED_INTERIM_SEC=1.2
+# CODESCRIBE_BUFFERED_CORRECTION_PREFIX=0.50
+CODESCRIBE_STREAM_CHUNK_SEC=2.0
+CODESCRIBE_STREAM_OVERLAP_RATIO=0.25
+# CODESCRIBE_BUFFER_DELAY_MS=280
+# CODESCRIBE_TYPING_CPS=90
+# CODESCRIBE_EMIT_WORDS_MAX=2
+CODESCRIBE_STREAM_SIMILARITY=0.90
+CODESCRIBE_STREAM_NOVELTY=0.20
+# CODESCRIBE_STREAM_DISABLE_EMBEDDINGS=1
+# CODESCRIBE_STREAM_FORCE_EMBEDDINGS=1
+# CODESCRIBE_STREAM_LEXICON=1
+# CODESCRIBE_STREAM_LOG=1
+# CODESCRIBE_STREAM_LOG_PATH=/tmp/codescribe_stream.log
+
+# =============================================================================
+# VAD (SILERO)
+# =============================================================================
+# VAD internals are hardcoded in core/vad/config.rs (Silero defaults).
+
+# =============================================================================
+# PATHS / STORAGE (ADVANCED)
+# =============================================================================
+# CODESCRIBE_DATA_DIR=/custom/data/dir
+# CODESCRIBE_ENV_PATH=/custom/.env
+
+# =============================================================================
+# EMBEDDER (E5) - RUNTIME OVERRIDES
+# =============================================================================
+# CODESCRIBE_EMBEDDER_PATH=/path/to/e5
+# CODESCRIBE_EMBEDDER_REPO=intfloat/multilingual-e5-small
+
+# =============================================================================
+# BUILD-TIME EMBEDDING (RELEASE ONLY)
+# =============================================================================
+# CODESCRIBE_NO_EMBED=1
+# CODESCRIBE_EMBED_MODEL=whisper-large-v3-turbo-mlx-q8
+# CODESCRIBE_EMBED_TTS=1
+# CODESCRIBE_TTS_PATH=/path/to/tts
 
 # =============================================================================
-# STREAMING TUNING (OPTIONAL)
+# LOGGING (OPTIONAL)
 # =============================================================================
-# CODESCRIBE_STREAM_CHUNK_SEC=12
-# CODESCRIBE_STREAM_OVERLAP_RATIO=0.25
-# CODESCRIBE_STREAM_SIMILARITY=0.90
-# CODESCRIBE_STREAM_NOVELTY=0.20
+# RUST_LOG=info
+# LOG_LEVEL=error

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Report a reproducible defect in CodeScribe
+title: "[bug] "
+labels: ["bug", "triage"]
+assignees: []
+---
+
+## Summary
+
+Describe the defect in one or two sentences.
+
+## Environment
+
+- CodeScribe version:
+- macOS version:
+- Device (Apple Silicon model):
+- Install mode (`make install`, `.app`, other):
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Logs / Diagnostics
+
+Attach relevant logs and output:
+
+- `codescribe -v` output
+- `codescribe-run.log` / `codescribe-debug.log`
+- screenshots if UI/overlay related
+
+## Additional Context
+
+Any other details that may help reproduction.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: mailto:security@vetcoders.io
+    about: Report security issues privately by email
+  - name: Team contact
+    url: mailto:hello@vetcoders.io
+    about: General project contact

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Propose an improvement or new capability
+title: "[feature] "
+labels: ["enhancement", "triage"]
+assignees: []
+---
+
+## Problem to Solve
+
+What workflow is currently difficult or blocked?
+
+## Proposed Solution
+
+Describe the behavior you want.
+
+## Alternatives Considered
+
+What other options did you evaluate?
+
+## Value / Impact
+
+Who benefits and how?
+
+## Scope
+
+- [ ] Core runtime
+- [ ] Agent / overlay
+- [ ] Settings UI
+- [ ] Packaging / distribution
+- [ ] Documentation
+
+## Additional Notes
+
+Mockups, references, or constraints.

.github/workflows/pages.yml

@@ -0,0 +1,40 @@
+name: Landing Pages
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "docs/landing/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build landing artifact
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/landing
+
+  deploy:
+    name: Deploy landing
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4