ShortGenerator/.github/copilot-instructions.md

# Coding pattern preferences

- Always prefer simple solutions
- Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality
- Write code that takes into account the different environments: dev, test, and prod
- You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested
- When fixing an issue or bug, do not introduce a new pattern or technology without first exhausting all options for the existing implementation. And if you finally do this, make sure to remove the old implementation afterwards so we don’t have duplicate logic.
- Keep the codebase very clean and organized
- Avoid having files over 500 lines of code. Refactor at that point.
- Mocking data is only needed for tests, never mock data for dev or prod
- Never add stubbing or fake data patterns to code that affects the dev or prod environments
- Never overwrite my .env file without first asking and confirming
- Never ask the user to provide the content of a specific file. Just open the file and check it yourself.
- Never create multiple files for sql execution. Always use a single file for all sql execution in a given migration.
- Never fix the symptoms of a problem, always fix the root cause of the problem.

# File Documentation Completion Requirements

**MANDATORY: When updating a file to "match the new copilot instructions", you MUST:**

1. **Complete the ENTIRE file** - Document every method, function, class, and significant code block
2. **Check for syntax errors** - Always verify the file compiles without errors after changes
3. **Test incrementally** - Use the get_errors tool after each major change to catch issues early
4. **Document systematically** - Go through the file from top to bottom, ensuring no method is left undocumented
5. **Maintain functionality** - Never break existing functionality while adding documentation
6. **Use proper comment syntax** - Always use the correct comment format for the programming language
7. **Validate completeness** - Before considering the task complete, review the entire file to ensure every function has documentation

**File Documentation Checklist:**

- [ ] File header with comprehensive description
- [ ] Every class documented with JSDoc
- [ ] Every method/function documented with JSDoc
- [ ] Every significant code block has educational comments
- [ ] Business context explained for complex logic
- [ ] Technical implementation details provided
- [ ] Error handling approaches documented
- [ ] Integration points with other modules explained
- [ ] No syntax errors remain in the file
- [ ] File compiles and functions properly

**If a file is large (>1000 lines):**

- Work in sections but complete ALL sections
- Add section dividers with clear documentation
- Use get_errors tool frequently to catch issues
- Test syntax after each major section
- Document the overall file architecture in the header

**Quality Standards:**

- Documentation should be educational and explain both WHAT and WHY
- Include business context for complex features
- Explain integration points and dependencies
- Use examples where helpful
- Write for developers who are new to the codebase

# Coding workflow preferences

- Focus on the areas of code relevant to the task
- Always use a surgical approach to code changes either removing or adding code while preserving all other functionalities.
- Do not touch code that is unrelated to the task
- Avoid making major changes to the patterns and architecture of how a feature works, after it has shown to work well, unless explicitly instructed
- Always think about what other methods and areas of code might be affected by code changes

## Configuration File Documentation

### For Configuration Files (package.json, tsconfig.json, etc.):

```javascript
/**
 * [Configuration Purpose]
 * Author: Dario Pascoal
 *
 * Description: [What this configuration controls and its main purpose]
 *
 * Important Notes: [Any critical information about changes or compatibility]
 */
```

## Version Control Guidelines

### Commit Message Standards

Follow conventional commit format:

- **feat**: New features or functionality
- **fix**: Bug fixes and corrections
- **docs**: Documentation updates (README, comments, etc.)
- **style**: Code formatting and style changes
- **refactor**: Code restructuring without functionality changes
- **test**: Adding or updating tests
- **chore**: Maintenance tasks, dependency updates

Examples:

- `feat: add SAP connection configuration panel`
- `fix: resolve memory leak in VBS process management`
- `docs: update README with new installation requirements`

# Code Documentation Requirements

## File Headers

Every source code file should include a comprehensive header:

### For TypeScript/JavaScript files:

```javascript
/**
 * [File Purpose/Component Name]
 * Author: Dario Pascoal
 *
 * Description: [Detailed explanation of what this file does, its main purpose,
 * and how it fits into the overall system. Explain it as if teaching someone
 * who is new to programming.]
 */
```

### For HTML/CSS files:

```css
/**
 * [File Purpose/Component Name]
 * Author: Dario Pascoal
 * 
 * Description: [Detailed explanation of what this file does, its main purpose,
 * and how it fits into the overall system. Explain it as if teaching someone
 * who is new to programming.]
 */
```

### For VBScript files (.vbs):

```vb
' [File Purpose/Component Name]
' Author: Dario Pascoal
'
' Description: [Detailed explanation of what this file does, its main purpose,
' and how it fits into the overall system. Explain it as if teaching someone
' who is new to programming.]
'
' [Additional sections as needed: Prerequisites, Parameters, Returns, etc.]
```

### For PowerShell files (.ps1):

```powershell
# [File Purpose/Component Name]
# Author: Dario Pascoal
#
# Description: [Detailed explanation of what this file does, its main purpose,
# and how it fits into the overall system. Explain it as if teaching someone
# who is new to programming.]
#
# [Additional sections as needed: Prerequisites, Parameters, Returns, etc.]
```

### CRITICAL: Language-Specific Comment Formatting

**ALWAYS use the correct comment syntax for each programming language:**

- **JavaScript/TypeScript**: Use `/** */` for file headers and `/* */` or `//` for inline comments
- **VBScript (.vbs)**: Use single quotes `'` for ALL comments - NEVER use `/** */` or `/* */`
- **PowerShell (.ps1)**: Use hash symbol `#` for ALL comments
- **HTML/CSS**: Use `/* */` for comments
- **Python**: Use `#` for comments and `"""` for docstrings
- **Batch files (.bat/.cmd)**: Use `REM` or `::` for comments

**This is mandatory** - using incorrect comment syntax will cause syntax errors and prevent scripts from executing properly.

## Function Documentation

Document functions with comprehensive JSDoc comments that explain both what and how:

```javascript
/**
 * [Clear description of what the function does and why it exists]
 *
 * [Detailed explanation of how the function works, step by step,
 * written for someone learning to code]
 *
 * @param {Type} paramName - Detailed explanation of what this parameter is,
 *                          what format it should be in, and how it's used
 * @returns {Type} Detailed explanation of what gets returned and when
 */
```

## Essential Comments - Write for Beginners

Focus comments on explaining code as if teaching someone new to programming:

- **Business logic**: Explain WHY certain decisions were made and WHAT the business requirement is
- **Complex algorithms**: Step-by-step explanation of HOW the code works
- **Integration points**: Explain HOW code connects to external systems and WHAT data flows between them
- **Non-obvious code**: Explain WHAT isn't immediately clear and WHY it works that way
- **Workarounds**: Explain WHAT the problem was and HOW this solution addresses it
- **Data structures**: Explain WHAT kind of data is stored and HOW it's organized
- **Control flow**: Explain WHAT conditions trigger different code paths and WHY

## Detailed Comment Guidelines

### Inline Comments - Explain the "What" and "Why"

Write comments that help a beginner understand:

- What each significant line or block of code is doing
- Why certain approaches were chosen
- What the expected input/output is at each step
- How different parts of the code work together
- What would happen if certain conditions are met

Example:

```javascript
// Check if the user has permission to access this feature
// This prevents unauthorized users from seeing sensitive data
if (user.hasPermission("admin")) {
  // Load the admin dashboard with all management tools
  // This includes user management, system settings, and reports
  loadAdminDashboard();
} else {
  // Show a basic user dashboard with limited functionality
  // Regular users only see their own data and basic features
  loadUserDashboard();
}
```

### Complex Logic Comments

For any complex business logic, algorithms, or multi-step processes:

```javascript
/**
 * PROCESS EXPLANATION:
 *
 * This function handles the complete user login workflow:
 * 1. First, it validates the username and password format
 * 2. Then it checks the credentials against the database
 * 3. If successful, it creates a secure session token
 * 4. Finally, it redirects the user to their appropriate dashboard
 *
 * The reason we do this in multiple steps is to provide better
 * error messages to the user and to log security events properly.
 */
```

## Comment Quality Standards

- **Be educational**: Write as if teaching a programming student
- **Explain assumptions**: State what the code assumes about inputs/environment
- **Describe data flow**: Explain what data goes in and what comes out
- **Clarify complex conditions**: Break down complicated if/else logic
- **Document error cases**: Explain what can go wrong and how it's handled
- **Use plain language**: Avoid jargon, explain technical terms when used
- **Provide context**: Explain how this code fits into the bigger picture# README Maintenance Requirements

## MANDATORY: README Updates

The project README.md file MUST be updated whenever making significant changes to the codebase. This ensures the documentation stays synchronized with the actual implementation.

### When to Update README:

**ALWAYS update the README when:**

- Adding new features or functionality
- Changing installation or setup procedures
- Modifying configuration requirements
- Adding new dependencies or technologies
- Changing project structure or architecture
- Adding new scripts or build processes
- Modifying environment variables or configuration files
- Updating system requirements or compatibility
- Adding new command-line interfaces or APIs
- Changing deployment procedures

### README Sections to Maintain:

1. **Project Description**: Keep the main purpose and features up-to-date
2. **Technology Stack**: Update when adding new technologies or frameworks
3. **Installation Instructions**: Verify and update setup steps
4. **Configuration**: Document new settings, environment variables, or config files
5. **Usage Examples**: Add examples for new features
6. **API Documentation**: Update when adding new endpoints or methods
7. **Development Setup**: Keep development environment instructions current
8. **Build and Deployment**: Update build scripts and deployment procedures
9. **Troubleshooting**: Add common issues and solutions
10. **Contributing Guidelines**: Update development and contribution processes

### README Update Standards:

- **Be Comprehensive**: Include all necessary information for new team members
- **Keep Examples Current**: Ensure all code examples work with the current version
- **Update Screenshots**: Replace outdated UI screenshots when interface changes
- **Maintain Accuracy**: Verify all instructions work on a clean environment
- **Version Information**: Update version numbers and compatibility information
- **Link Validation**: Ensure all links are current and functional

### README Quality Checklist:

Before committing code changes, verify:

- [ ] README reflects all new features and changes
- [ ] Installation instructions are accurate and complete
- [ ] All code examples are tested and working
- [ ] Configuration documentation is up-to-date
- [ ] System requirements are current
- [ ] Links and references are valid
- [ ] Screenshots and diagrams reflect current state
- [ ] Troubleshooting section addresses known issues

### Automatic README Triggers:

**High Priority Updates** - Always update README for:

- New major features or modules
- Changes to package.json dependencies
- Environment variable additions/changes
- New configuration files or formats
- Changes to build/deployment processes
- New user-facing functionality

**Medium Priority Updates** - Consider updating README for:

- Internal architecture changes that affect setup
- New development tools or workflows
- Performance improvements with user impact
- Security enhancements with configuration changes

The README should serve as the single source of truth for project onboarding, setup, and usage. Keep it comprehensive, accurate, and user-friendly.