docs: documentation improvements (#1772)

* docs: Add documentation improvement plan and PRD

* docs: Update documentation files and reflect progress in PROJECT_IMPROVEMENTS.md

* updated copilot instructions and adding small architecture doces

* docs: Add missing example usage and configuration examples to configuration.md

- Added example usage section showing command-line and config.json usage
- Added Electron CLI flags configuration examples
- Added incoming call command configuration examples
- Added cache management configuration section with detailed options
- Moved examples from README that were removed during documentation improvements

This restores the comprehensive configuration examples that were previously
available in the README and consolidates them in the dedicated configuration
documentation.

* docs: Add knowledge base improvements to documentation initiative

- Added Knowledge Base Improvements as priority 1.4 in PROJECT_IMPROVEMENTS.md
- Added section 3.4 Knowledge Base Improvements in PRD document
- Updated PRD timeline to include knowledge base creation from GitHub issues data
- Comprehensive plan to leverage collected GitHub issues for troubleshooting guide

* cleanup: Remove GitHub issues analysis scripts and data

- Removed data/github_issues/ directory with all downloaded issue JSON files
- Removed scripts/analyze_github_issues.py and scripts/fetch_github_issues.py
- Removed docs/github_issues_analysis_report.md
- These files were used for analysis but are not needed in the repository
- The knowledge gained will be incorporated into the documentation improvements

* docs: Add strategic JSDoc comments and explanations for complex patterns

- Added JSDoc to AppConfiguration class explaining WeakMap private field pattern
- Documented command line switch handling in main index.js with rationale
- Explained aboutBlankRequestCount authentication flow pattern
- Added comprehensive JSDoc for certificate validation in corporate environments
- Documented Teams protocol handling and URL processing in processArgs
- Explained iframe CSS injection workaround for Teams V2
- Added CustomNotification class documentation for notification interception

Strategic comments focus on non-obvious design decisions, security implications,
and unusual patterns rather than restating obvious code functionality.

* docs: Mark JSDoc comments as completed in PROJECT_IMPROVEMENTS.md

Updated status to reflect completion of strategic JSDoc and code-level comments.
Focus was on documenting non-obvious patterns, complex logic, and unusual
design decisions rather than obvious code functionality.

* docs: Add comprehensive IPC API documentation

- Created docs/ipc-api.md with complete IPC channel reference
- Documented all ipcMain.handle and ipcMain.on channels across modules
- Included parameters, return values, and usage examples for each channel
- Added communication patterns and debugging guidance
- Updated PROJECT_IMPROVEMENTS.md to mark API documentation as completed

Addresses Priority 1.7 Documentation Improvements initiative

* docs: Integrate KNOWN_ISSUES.md into knowledge-base.md and update PROJECT_IMPROVEMENTS.md

This commit integrates the content from KNOWN_ISSUES.md into the new knowledge-base.md, providing a centralized location for common issues and solutions. It also updates the PROJECT_IMPROVEMENTS.md to reflect the completion of this sub-task.

* docs: Update documentation links and remove KNOWN_ISSUES.md

Updated all internal documentation links to point to the new centralized documentation location in the docs/ folder. Removed the KNOWN_ISSUES.md file as its content has been merged into docs/knowledge-base.md.

* docs: Finalize documentation updates and minor code formatting

This commit includes the final updates to PROJECT_IMPROVEMENTS.md and README.md, reflecting the completed documentation tasks. It also incorporates minor formatting adjustments and comment rephrasing in several app files that were inadvertently modified during previous operations.

* docs: Move Multiple Instances documentation to docs folder

Moved app/config/MULTIPLE_INSTANCES.md to docs/multiple-instances.md and updated PROJECT_IMPROVEMENTS.md to reflect this change.

* added improved instruction files to start using tasks to process the jobs

* docs: Move documentation files to docs folder and update links

Moved Custom Backgrounds, LogConfig, and Certificate READMEs to the docs folder. Created a new cache-manager.md and merged content from the old Cache Manager README. Updated relevant links in app/config/README.md and PROJECT_IMPROVEMENTS.md.

* Update docs/knowledge-base.md

Co-authored-by: Copilot <[email protected]>

* fixing some paths for the docs

* docs: enhance instruction files with markdown standards

- Add comprehensive Markdown Standards sections to all instruction files

- Emphasize using GitHub's built-in features (TOC, alerts, Mermaid) over custom solutions

- Ensure consistency across create-prd, generate-tasks, process-tasks-list, and copilot instructions

- Promote maintainable documentation practices using existing markdown library features

* feat: Add comprehensive AI research and PRD documentation

- Create docs/ai-research/ directory for strategic analysis and insights
- Add documentation-health-analysis.md with comprehensive assessment (8.5/10 rating)
- Add ui-system-strategic-analysis.md with implementation recommendations
- Create prd-in-app-ui-system.md with detailed product requirements
- Update GEMINI.md to reference docs/ directory for instructions
- Establish foundation for knowledge base improvements and in-app UI system

These documents capture strategic insights for future development decisions
and provide comprehensive analysis of documentation quality and proposed
feature alignment with project goals.

* increasing the vesrion number

---------

Co-authored-by: Copilot <[email protected]>

Author: IsmaelMartinez

.github/copilot-instructions.md

@@ -2,55 +2,86 @@
 
 ## Project Overview
 
-Teams for Linux is an Electron-based desktop application that wraps Microsoft Teams web app for Linux users. The app provides a native desktop experience with additional features like custom CSS, backgrounds, notifications, and system integration.
+Teams for Linux is an Electron-based desktop application that wraps the Microsoft Teams web app, providing a native desktop experience for Linux users. The app enhances the web version with features like custom CSS, custom backgrounds, system notifications, and deep integration with the desktop environment.
+
+## Project Vision & Refactoring Goals
+
+The project is currently undergoing a strategic effort to improve its architecture, maintainability, and developer experience. Key goals include:
+
+- **Increased Modularity:** Refactoring the monolithic `app/index.js` into smaller, single-responsibility modules (e.g., for IPC handling, command-line parsing, notification management).
+- **Modernization:** Adopting modern JavaScript features (`async/await`, `const`/`let`) and simplifying patterns (e.g., class private fields).
+- **Robustness:** Implementing comprehensive error handling, structured logging, and centralized state management.
+- **Testability:** Introducing a formal testing framework to build a suite of unit and integration tests.
+- **Clarity:** Enhancing documentation across all levels of the project.
+
+When contributing, please align your changes with these goals.
 
 ## Architecture & Key Components
 
 ### Main Application Structure
 
-- **Entry Point**: `app/index.js` - Main Electron process with app lifecycle management
-- **Configuration**: `app/appConfiguration/` - Centralized config management using electron-store
-- **Main Window**: `app/mainAppWindow/` - BrowserWindow management and Teams web app wrapper
-- **Browser Tools**: `app/browser/tools/` - Client-side scripts injected into Teams web interface
-
-### Key Modules
-
-- **Notifications**: `app/browser/notifications/` - Activity tracking and desktop notifications
-- **Cache Management**: `app/cacheManager/` - Automatic cache cleanup to prevent OAuth token corruption
-- **Custom Features**:
-  - `app/customCSS/` - User-defined styling injection
-  - `app/customBackground/` - Custom Teams background support
-  - `app/spellCheckProvider/` - Multi-language spell checking
-- **System Integration**:
-  - `app/menus/` - Application and tray menus
-  - `app/connectionManager/` - Network connection handling
-  - `app/certificate/` - SSL certificate management
-  - `app/incomingCallToast/` - Custom toast for incoming calls
-  - `app/streamSelector/` - Stream selection for screen sharing
+- **Entry Point**: `app/index.js` - Main Electron process. **Note:** This file is being actively refactored. New functionalities should be placed in separate, dedicated modules rather than being added here directly.
+- **Configuration**: `app/appConfiguration/` - Centralized configuration management. See `docs/configuration.md` for a detailed breakdown of all options.
+- **Main Window**: `app/mainAppWindow/` - Manages the main `BrowserWindow` and the Teams web app wrapper.
+- **Browser Tools**: `app/browser/tools/` - Client-side scripts injected into the Teams web interface.
+
+### Key Documentation
+
+- **Architecture Diagrams**: See `docs/architecture/` for visual overviews of the system.
+- **Configuration Details**: See `docs/configuration.md`.
+- **IPC API**: See `docs/ipc-api.md` for a list of all IPC channels.
+- **Module-specific READMEs**: Each subdirectory in `app/` should have a `README.md` explaining its purpose and interactions.
 
 ## Development Patterns
 
 ### Configuration Management
 
-```javascript
-// All config through AppConfiguration class
-const { AppConfiguration } = require("./appConfiguration");
-const appConfig = new AppConfiguration(
-  app.getPath("userData"),
-  app.getVersion()
-);
-```
+- All configuration is managed through the `AppConfiguration` class.
+- **Guiding Principle:** Treat the configuration object as immutable after startup. Changes should be managed via methods within `AppConfiguration` to ensure consistency.
+- For class properties, prefer standard JavaScript private fields (`#property`) over `WeakMap` for simplicity and readability.
+
+### State Management
+
+- Avoid using global variables.
+- For state shared between modules (e.g., `userStatus`, `aboutBlankRequestCount`), create or use a dedicated state management module to provide controlled access and modification methods.
 
-### Browser Script Injection
+### Event Communication (IPC)
 
-- Scripts in `app/browser/tools/` are injected into Teams web interface
-- Use `window.addEventListener('DOMContentLoaded')` pattern for DOM manipulation
-- Follow existing patterns in `reactHandler.js` and `settings.js`
+- **Current State:** IPC is handled via `ipcMain.on` and `ipcMain.handle` calls, primarily in `app/index.js`.
+- **Future Direction:** We are moving towards a centralized event bus or IPC abstraction layer to improve structure and maintainability. New IPC channels should be well-documented in `docs/ipc-api.md`.
 
-### Event Communication
+### Modern JavaScript Practices
 
-- Main process ↔ Renderer: Standard Electron IPC patterns
-- Browser scripts ↔ Main: Custom event dispatching through DOM events
+- **`var` is disallowed.** Use `const` by default and `let` only when a variable must be reassigned.
+- Use `async/await` for all asynchronous operations instead of promise chains (`.then()`).
+- Use arrow functions for concise callbacks.
+
+### Error Handling & Logging
+
+- Implement a robust error handling strategy using `try-catch` blocks in `async` functions.
+- Aim for graceful degradation and provide clear user feedback for errors.
+- Use `electron-log` for structured logging. Ensure log levels are used consistently and avoid logging sensitive information.
+
+## Documentation
+
+- **A Core Responsibility:** Documentation is not an afterthought; it is a core part of the development process.
+- **Update as You Go:** When you make a code change, update the relevant documentation in the same pull request.
+- **Module READMEs:** Ensure the `README.md` in the module you are working on is up-to-date.
+- **Code Comments:** Add comments sparingly. Focus on the _why_ behind complex, non-obvious, or unusual code, not the _what_. Use JSDoc for public APIs.
+- **Central Docs:** For changes affecting configuration, IPC, or overall architecture, update the corresponding documents in the `/docs` directory.
+
+## Markdown Standards
+
+When creating or updating documentation, leverage existing markdown library features instead of building custom solutions:
+
+- **Table of Contents:** Use GitHub's `<!-- toc -->` element for automatic TOC generation instead of manual lists
+- **Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]`) for important information, warnings, and critical notes
+- **Code Blocks:** Use proper syntax highlighting with language identifiers (e.g., `javascript, `bash)
+- **Tables:** Use standard markdown tables with proper alignment for structured data
+- **Checkboxes:** Use standard GitHub checkbox syntax `- [ ]` and `- [x]` for task tracking and checklists
+- **Links:** Use relative paths for internal documentation links and absolute URLs for external resources
+- **Collapsible Sections:** Use GitHub's `<details>` and `<summary>` elements for optional or lengthy information
+- **Diagrams:** Consider GitHub's Mermaid support for flowcharts, sequence diagrams, and architecture diagrams when applicable
 
 ## Build & Development
 
@@ -65,38 +96,27 @@ npm run pack          # Development build without packaging
 
 ### Build Configuration
 
-- **electron-builder** config in `package.json` under `"build"` section
-- Platform-specific builds: Linux (primary), macOS, Windows
-- Multiple output formats: AppImage, deb, rpm, snap, tar.gz
-
-### Release Process
-
-- Automated via GitHub Actions (`.github/workflows/build.yml`)
-- Version managed in `package.json` and propagated to build metadata
-- Release info generated by `scripts/generateReleaseInfo.js`
-- Debian changelog generated by `scripts/generateDebianChangelog.js` for proper package management
+- **electron-builder** config in `package.json` under the `"build"` section.
+- Release process is automated via GitHub Actions (`.github/workflows/build.yml`).
 
 ## Testing & Quality
 
-- **Linting**: ESLint with custom config (`eslint.config.mjs`)
-- **Security**: Snyk integration for vulnerability scanning
-- **Code Quality**: SonarCloud integration
-- **CI/CD**: GitHub Actions for build validation and releases
+- **Linting**: ESLint with custom config (`eslint.config.mjs`) is mandatory.
+- **Security**: Snyk and CodeQL for vulnerability scanning.
+- **CI/CD**: GitHub Actions for build validation and releases.
+- **Unit & Integration Testing**: The project currently lacks sufficient test coverage. A key goal is to introduce a testing framework (e.g., Jest) and build out a comprehensive test suite. Contributions in this area are highly encouraged.
 
 ## Common Patterns
 
-- **Single Instance**: The application ensures only a single instance is running using `app.requestSingleInstanceLock()`.
-- **Command Line Switches**: Various command-line switches are appended (e.g., for Wayland/PipeWire, proxy settings, disabling GPU, and custom Electron CLI flags from config).
-- Use `electron-log` for logging throughout the application
-- Configuration changes require app restart (document this in features)
-- Browser scripts should be defensive against Teams web app changes
-- Follow existing error handling patterns in main modules
+- **Single Instance**: The app uses `app.requestSingleInstanceLock()` to ensure only one instance is running.
+- **Command Line Switches**: The app processes various command-line switches. Logic for this is being centralized from `app/index.js` into a dedicated module.
+- **Defensive Coding:** Browser scripts should be written defensively, as the Teams web app DOM can change without notice.
 
 ## External Dependencies
 
-- **Core**: Electron, electron-builder for packaging
-- **System**: @homebridge/dbus-native for Linux desktop integration
-- **Storage**: electron-store for persistent configuration
-- **Audio**: node-sound for notification sounds (optional dependency)
+- **Core**: Electron, electron-builder
+- **System**: @homebridge/dbus-native (Linux desktop integration)
+- **Storage**: electron-store (persistent configuration)
+- **Audio**: node-sound (optional, for notification sounds)
 
 When working on this codebase, always consider cross-platform compatibility and the fact that the Teams web interface can change independently of this application.

.github/instructions/create-prd.instructions.md

@@ -0,0 +1,80 @@
+---
+description: Generate Product Requirements Documents (PRDs) for features
+globs:
+alwaysApply: false
+---
+
+# Rule: Generating a Product Requirements Document (PRD)
+
+## Goal
+
+To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
+
+## Process
+
+1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
+2. **Ask Clarifying Questions:** Before writing the PRD, the AI _must_ ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out). Make sure to provide options in number.letter lists so I can respond easily with my selections.
+3. **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
+4. **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/tasks` directory.
+
+## Clarifying Questions (Examples)
+
+The AI should adapt its questions based on the prompt, but here are some common areas to explore:
+
+- **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?"
+- **Target User:** "Who is the primary user of this feature?"
+- **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
+- **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
+- **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?"
+- **Scope/Boundaries:** "Are there any specific things this feature _should not_ do (non-goals)?"
+- **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
+- **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?"
+- **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
+- **Existing Solutions Research:** "Are there existing SaaS tools, libraries, or software solutions that already solve this problem?" or "Have you researched what alternatives are currently available in the market?"
+- **Build vs. Buy Analysis:** "Should we consider integrating with an existing solution rather than building from scratch?" or "What are the pros and cons of building this internally versus using a third-party service?"
+- **Solution Evaluation Criteria:** "If multiple implementation options are available, what criteria should we use to evaluate them? (e.g., cost, maintenance overhead, feature completeness, integration complexity, vendor lock-in, etc.)"
+
+## PRD Structure
+
+The generated PRD should include the following sections:
+
+1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
+2. **Goals:** List the specific, measurable objectives for this feature.
+3. **User Stories:** Detail the user narratives describing feature usage and benefits.
+4. **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
+5. **Non-Goals (Out of Scope):** Clearly state what this feature will _not_ include to manage scope.
+6. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
+7. **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module"). _When proposing MCP servers, consider if official versions exist (e.g., Supabase MCP server)._ Include research on existing solutions:
+   - List and evaluate available SaaS tools, libraries, or third-party services that could solve this problem
+   - Provide build vs. buy analysis when applicable
+   - If multiple options exist, include evaluation criteria and recommendations
+   - Consider factors like: cost, maintenance overhead, vendor lock-in, integration complexity, feature completeness, and long-term viability
+8. **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
+9. **Open Questions:** List any remaining questions or areas needing further clarification.
+
+## Target Audience
+
+Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `/tasks/`
+- **Filename:** `prd-[feature-name].md`
+
+## Markdown Standards
+
+When creating PRDs, leverage existing markdown library features instead of building custom solutions:
+
+- **Table of Contents:** Use GitHub's `<!-- toc -->` element for automatic TOC generation instead of manual lists
+- **Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, etc.) for important information
+- **Code Blocks:** Use proper syntax highlighting with language identifiers
+- **Tables:** Use standard markdown tables with proper alignment
+- **Links:** Use relative paths for internal documentation links
+- **Diagrams:** Consider GitHub's Mermaid support for flowcharts and diagrams when applicable
+
+## Final instructions
+
+1. Do NOT start implementing the PRD
+2. Make sure to ask the user clarifying questions
+3. Take the user's answers to the clarifying questions and improve the PRD