refactor(config): consolidate network endpoint configuration

[SystemicVoid]

Issue

Network endpoint configuration (ports, hosts, URLs) is duplicated across shell scripts, Python, Rust, and documentation.

Problem

Default network endpoints are scattered across multiple locations:

Port 8765 (daemon):

• scripts/stt-helper.sh:71 - Shell default
• parakeet-stt-daemon/src/parakeet_stt_daemon/config.py:16 - Python default
• parakeet-stt-daemon/README.md:5-7 - Documentation
• docs/stt-troubleshooting.md:74 - Documentation

Port 8080 (LLM):

• scripts/stt-helper.sh:87 - Shell default
• scripts/stt-helper.sh:126 - Help text
• parakeet-ptt/src/main.rs:70 - Rust default

Host 127.0.0.1:

• scripts/stt-helper.sh:70,86 - Shell defaults
• parakeet-stt-daemon/src/parakeet_stt_daemon/config.py:15 - Python default
• parakeet-ptt/src/main.rs:2760 - Rust endpoint
• parakeet-ptt/src/config.rs:12 - Rust default

Full WebSocket endpoint:

• parakeet-ptt/src/config.rs:12 - ws://127.0.0.1:8765/ws
• parakeet-ptt/src/main.rs:2760 - ws://127.0.0.1:8765/ws
• README.md:79 - Documentation

DRY Violation

The knowledge of "default network endpoints" is scattered. Changing the default port requires updating 5+ locations, increasing risk of inconsistencies.

Proposed Fix

Create a shared configuration file that defines network defaults:

1. Create config/network.toml or similar config file with:

   [daemon]
   host = "127.0.0.1"
   port = 8765
   
   [llm]
   host = "127.0.0.1"
   port = 8080
   base_path = "/v1"

2. Update each component to read from the shared config:

   • Shell: Parse TOML or source the values
   • Python: Use tomllib (Python 3.11+) or tomli
   • Rust: Use serde_toml or similar

3. Update documentation to reference the config file

4. Ensure backward compatibility with environment variable overrides

Alternative: Keep hardcoded but document centrally

Instead of a config file, document all default values in a single location (e.g., docs/SPEC.md or a dedicated config reference document).

Tasks

• Determine approach: config file vs centralized documentation
• Create config file structure with all network defaults
• Update shell script to read config (or source a generated script)
• Update Python daemon to read config
• Update Rust client to read config
• Update all documentation references
• Ensure environment variables still work as overrides
• Test all components with default and custom endpoints
• Run quality checks (prek run)

Tradeoffs

Approach	Pros	Cons
Generate config from single source	Single source of truth, docs can be generated	Requires build-time generation or separate config file
Environment variable-only defaults	Centralized at runtime	Still needs documentation somewhere
Shared config file (TOML)	Human-readable, can be versioned	Requires reading/parsing logic in multiple languages
Keep as-is with clear documentation	Simple, no build changes	Violates DRY, manual sync required

Design Considerations

• The shell script's stt help start command derives help from start_option_rows - consider if config should feed into this
• Backward compatibility is important - existing environment variable overrides must continue to work
• Config file should be optional, with fallback to current hardcoded defaults

Files to Modify

• New: config/network.toml (or similar)
• scripts/stt-helper.sh (read config)
• parakeet-stt-daemon/src/parakeet_stt_daemon/config.py (read config)
• parakeet-ptt/src/config.rs (read config)
• Documentation files (update references)

---

AI-Generated Disclaimer: This issue was generated by AI analysis and may contain errors. Please thoroughly verify the findings before implementing any changes. Review the code directly and test any modifications.