AIGuardian Troubleshooting Guide (v1.1.0)

If you run into any issues with AIGuardian, this guide will help you solve common problems.

Installation Problems

"Command not found" after installation

If you see aiguardian: command not found after installing:

1. 1. Try closing and reopening your terminal/command prompt

1. 2. If that doesn't work, try installing again with:

   npm install -g aiguardian
   

1. 3. Make sure Node.js is properly installed by typing:

   node --version
   

If this doesn't show a version number, you need to reinstall Node.js

Installation errors with npm

If you see errors during installation:

1. 1. Make sure you have the latest version of npm:

   npm install -g npm
   

1. 2. Try installing with administrator privileges:
- Windows: Right-click command prompt and select "Run as administrator" - Mac/Linux: Use sudo npm install -g aiguardian

Usage Problems

AIGuardian can't detect my project type

If AIGuardian doesn't correctly identify your project:

1. 1. Make sure you're running AIGuardian in the main folder of your project
1. 2. Check if your project has the typical files for its type (like package.json for JavaScript/Node.js)
1. 3. You can still select tasks manually even if detection isn't perfect

AIGuardian is too slow

If AIGuardian seems to take a long time:

1. 1. Try running it on a smaller part of your project first
1. 2. Use the --verbose option to see what's happening:

   aiguardian --verbose
   

1. 3. Try running specific tasks with the --task option:

   aiguardian --task clean-gitignore
   

1. 4. Use the --yes option to skip confirmation prompts:

   aiguardian --yes
   

Changes made by AIGuardian broke my project

If something doesn't work after using AIGuardian:

1. 1. Don't panic! AIGuardian creates backups before making changes
1. 2. Look in the .aiguardian/backups folder in your project
1. 3. The backups are ZIP files named with timestamps
1. 4. Extract the most recent backup to restore your files

Common Error Messages

"No tasks applicable for this project"

This means AIGuardian couldn't find tasks suitable for your project:

1. 1. Make sure you're in the correct project folder
1. 2. Your project might be in a format AIGuardian doesn't recognize
1. 3. Try running specific tasks manually

"Permission denied" errors

If you see permission errors:

1. 1. Make sure you have write permission to the files in your project
1. 2. Try running AIGuardian with administrator privileges

Command Line Options

If you're having trouble with command line options, here's a quick reference:

Options:
  -p, --path    Path to project directory (default: current directory)
  -d, --dry-run       Run without making changes
  -v, --verbose       Show detailed logs
  -y, --yes           Skip confirmation prompts
  -t, --task      Run specific task (can be used multiple times)
  -a, --all           Run all available tasks
  --no-backup         Skip backup creation
  -h, --help          Display help information

For example, to run all tasks without confirmation:

aiguardian --all --yes

Or to run a specific task in dry-run mode:

aiguardian --task clean-gitignore --dry-run

Getting More Help

If you're still having issues:

1. 1. Check the official AIGuardian documentation
1. 2. Visit the GitHub repository to search for similar issues
1. 3. Ask for help in the discussions section on GitHub
1. 4. Submit a bug report if you've found a new issue