[Research]: Evaludate adding command line arguments, bundle an mqtt server and supporting commands/actions in our mqtt implementation

docs-site/docs/development/adr/004-cli-argument-parsing-library.md

@@ -0,0 +1,96 @@
+# ADR 004: CLI Argument Parsing Library Decision
+
+**Status:** Accepted
+**Date:** 2025-11-16
+**Deciders:** Development Team
+**Related:** MQTT Commands Research
+
+---
+
+## Context
+
+Teams for Linux uses `yargs` for CLI argument parsing. We evaluated whether to:
+1. Add CLI-based action commands (`teams-for-linux action toggle-mute`)
+2. Migrate to `commander.js` for better subcommand support
+3. Keep current `yargs` implementation
+
+### Requirements
+- Support 30+ configuration options
+- Parse config files and environment variables
+- Handle meeting URLs as positional arguments (`teams-for-linux https://teams.microsoft.com/...`)
+- Low risk of breaking existing functionality
+
+### Considered Options
+
+**Option A: Add CLI Action Commands with yargs**
+- Requires fragile pre-parsing before yargs initialization
+- High risk of breaking meeting link flow (critical feature)
+- Conflicts with existing URL positional argument handling
+- Effort: 14-23 hours
+
+**Option B: Migrate to commander.js**
+- Better subcommand support
+- Requires reimplementing config file and environment variable parsing
+- 30+ options need migration
+- Effort: 6-8 hours
+- Risk: Medium (regression testing needed)
+
+**Option C: Keep yargs, Use Alternative Command Mechanism**
+- MQTT for actions (see MQTT Commands Research)
+- HTTP server for actions
+- No CLI parsing changes needed
+- Effort: 4-6 hours
+- Risk: Low (isolated addition)
+
+---
+
+## Decision
+
+**Stick with yargs. Do not add CLI action commands. Use MQTT for action triggers.**
+
+### Rationale
+
+1. **yargs is appropriate for current use case**
+   - Config-heavy application (30+ options)
+   - Built-in config file and environment variable support
+   - No need for subcommands (actions handled via MQTT)
+
+2. **Avoid fragile bypass layer**
+   - Pre-parsing arguments before yargs creates tight coupling
+   - High risk of breaking meeting link handling
+   - Difficult to maintain
+
+3. **Better alternatives exist**
+   - MQTT commands: Clean architecture, extensible, low risk
+   - HTTP server: Zero external dependencies for shortcuts
+   - No need for complex CLI parsing
+
+4. **Future-proofing**
+   - Can migrate to commander.js during major version bump (v2.0+) if multiple subcommands become necessary
+   - Current architecture works well for current needs
+
+---
+
+## Consequences
+
+### Positive
+- ✅ No risk to existing functionality (meeting links, config options)
+- ✅ No migration effort
+- ✅ Built-in config/env parsing continues working
+- ✅ Users get action commands via MQTT (better UX anyway)
+
+### Negative
+- ⚠️ No native CLI subcommands (not needed currently)
+- ⚠️ Future subcommand needs require migration or workarounds
+
+### Neutral
+- Option to migrate to commander.js remains open for future major versions
+- Decision can be revisited if requirements change significantly
+
+---
+
+## References
+
+- [CLI Arguments vs MQTT Comparison](../research/mqtt-commands-implementation.md)
+- [yargs Documentation](https://yargs.js.org/)
+- [commander.js Documentation](https://github.com/tj/commander.js)

docs-site/docs/development/adr/005-embedded-mqtt-broker.md

@@ -0,0 +1,221 @@
+# ADR 005: Embedded MQTT Broker Decision
+
+**Status:** Rejected
+**Date:** 2025-11-16
+**Deciders:** Development Team
+**Related:** [MQTT Commands Research](../research/mqtt-commands-implementation.md)
+
+---
+
+## Context
+
+With MQTT commands implementation planned, we evaluated whether to bundle an embedded MQTT broker (Aedes) in the Electron app to simplify user setup.
+
+### Problem
+
+Users need an MQTT broker to:
+1. Receive status updates from Teams
+2. Send action commands to Teams
+
+Without a broker, users must:
+- Install mosquitto: `sudo apt-get install mosquitto`
+- Configure and start the service
+- Understand MQTT concepts
+
+### Proposed Solution
+
+Bundle Aedes (JavaScript MQTT broker) in the Electron app:
+- Auto-starts when app launches
+- Listens on `localhost:1883`
+- Zero configuration needed
+- Bundle size: +230 KB
+- Implementation effort: 6-8 hours
+
+---
+
+## Decision
+
+**Do NOT bundle an embedded MQTT broker.**
+
+---
+
+## Rationale
+
+### 1. Doesn't Solve the Real Problem
+
+**Users still need MQTT client tools** to send commands:
+
+```bash
+# Even with embedded broker, users must install:
+sudo apt-get install mosquitto-clients
+
+# To run:
+mosquitto_pub -h localhost -t teams/command -m '{"action":"toggle-mute"}'
+```
+
+**Embedded broker eliminates:**
+- Installing mosquitto broker
+
+**Embedded broker does NOT eliminate:**
+- Installing mosquitto-clients (for `mosquitto_pub`)
+- Creating wrapper scripts
+- Understanding MQTT topics
+
+**Conclusion:** Marginal benefit (removes 1 of 3 installation steps)
+
+---
+
+### 2. Wrong Architectural Pattern
+
+**Teams should be a client, not a broker.**
+
+```
+❌ Wrong: Each Teams instance runs its own broker
+    Teams Instance 1 → Aedes broker :1883
+    Teams Instance 2 → Aedes broker :1884 (port conflict!)
+    Home Assistant → Mosquitto :1883
+    → Fragmented ecosystem
+
+✅ Right: Centralized broker, multiple clients
+    Mosquitto :1883 (or Home Assistant MQTT add-on)
+        ├─ Teams for Linux (client)
+        ├─ Home Assistant (client)
+        ├─ Node-RED (client)
+        └─ IoT devices (clients)
+    → Unified ecosystem
+```
+
+Users with home automation already have MQTT brokers. Creating another broker fragments their setup.
+
+---
+
+### 3. Better Alternatives Exist
+
+**For users wanting keyboard shortcuts with zero dependencies:**
+
+**Option A: HTTP Server**
+```bash
+# curl is pre-installed on all Linux systems
+curl -X POST http://localhost:48765/action/toggle-mute
+```
+- ✅ No package installation
+- ✅ Simpler than MQTT
+- ✅ Can serve web UI
+
+**Option B: Named Pipe (FIFO)**
+```bash
+# echo is built-in
+echo '{"action":"toggle-mute"}' > ~/.config/teams-for-linux/commands.fifo
+```
+- ✅ Zero external dependencies
+- ✅ Standard Unix IPC
+
+**For users with home automation:**
+- They already have MQTT brokers (Home Assistant, etc.)
+- Prefer connecting to existing broker
+- Embedded broker adds unnecessary complexity
+
+---
+
+### 4. Implementation Complexity Without Value
+
+| Component | Embedded Broker | External Broker | HTTP Server |
+|-----------|----------------|-----------------|-------------|
+| Bundle size | +230 KB | 0 KB | 0 KB |
+| Implementation | 6-8 hours | 0 hours | 3-4 hours |
+| User dependencies | mosquitto-clients | mosquitto + mosquitto-clients | None (curl) |
+| Port conflicts | Yes (need handling) | No | Rare |
+| Maintenance | Update Aedes | User manages | None |
+
+**Cost/benefit:** Not favorable
+
+---
+
+## Consequences
+
+### Positive
+- ✅ Simpler architecture (Teams = client only)
+- ✅ No port conflict handling needed
+- ✅ No Aedes dependency to maintain
+- ✅ Users with existing MQTT get better integration
+- ✅ Saved 6-8 hours implementation effort
+
+### Negative
+- ⚠️ Users without MQTT must install mosquitto
+- ⚠️ Slightly higher barrier to entry for MQTT features
+
+### Mitigations
+- Document easy broker setup (apt-get one-liner for most distros)
+- Recommend Home Assistant MQTT add-on (one-click install)
+- Consider HTTP server for zero-dependency shortcuts (future)
+
+---
+
+## Alternatives Considered
+
+### Alternative 1: HTTP Command Server (Future)
+
+**For users wanting shortcuts without MQTT:**
+
+```javascript
+// Serve HTTP endpoint
+http://localhost:48765/action/toggle-mute
+
+// User script (no dependencies)
+curl -X POST http://localhost:48765/action/toggle-mute
+```
+
+**Advantages:**
+- ✅ curl is pre-installed
+- ✅ Simpler than MQTT for basic use
+- ✅ Can add web UI later
+
+**Status:** Consider for future implementation
+
+### Alternative 2: Keep MQTT, Document Broker Setup
+
+**For users with home automation:**
+
+Document connecting to existing brokers:
+- Home Assistant MQTT add-on
+- Existing mosquitto installation
+- Cloud MQTT providers (for advanced users)
+
+**Status:** Accepted (current plan)
+
+---
+
+## User Segments
+
+### Segment 1: Home Automation Users (30%)
+- Already have MQTT broker
+- Want Teams integration with automations
+- **Solution:** Connect to existing broker (documented)
+
+### Segment 2: Keyboard Shortcut Users (50%)
+- Want simple system-wide shortcuts
+- Don't have MQTT infrastructure
+- **Solution:** Install mosquitto (documented) OR HTTP server (future)
+
+### Segment 3: Advanced Users (20%)
+- Can set up whatever they need
+- **Solution:** Any approach works
+
+---
+
+## References
+
+- [MQTT Commands Implementation Research](../research/mqtt-commands-implementation.md)
+- [Aedes MQTT Broker](https://github.com/moscajs/aedes)
+- Related: HTTP command server (future consideration)
+
+---
+
+## Review
+
+This decision should be reviewed if:
+1. A zero-dependency command mechanism becomes critical requirement
+2. MQTT adoption is very low due to broker installation complexity
+3. Implementation effort for embedded broker drops significantly (new library, etc.)
+
+For now: **Proceed with MQTT client only + document broker setup.**