# Quick Start Guide

## Initial Setup

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Create placeholder icons (optional for development):**

   The app includes placeholder icon files, but you may want to replace them with actual images:
   - `src/assets/icons/tray-icon.png` (22x22px)
   - `src/assets/icons/tray-icon@2x.png` (44x44px)

   See `src/assets/icons/README.md` for details.

## Development

### Option 1: Automatic (Recommended for rapid development)

Run both the main and renderer processes in watch mode, then start Electron:

```bash
# Terminal 1: Start development servers
npm run dev

# Terminal 2: Start Electron (after main process compiles)
npm start
```

### Option 2: Manual (More control)

```bash
# Terminal 1: Watch main process
npm run dev:main

# Terminal 2: Watch renderer process
npm run dev:renderer

# Terminal 3: Start Electron
npm start
```

### Development Tips

- **Hot Reload**: The renderer process (React UI) will hot-reload automatically
- **Main Process**: Restart Electron (Ctrl+C and `npm start`) to see main process changes
- **Settings Window**: Press `Cmd+,` or click Settings in the menu bar
- **Quit**: Press `Cmd+Q` or click Quit in the menu bar

## First Run

When you first run the app:

1. Look for the app icon in your macOS menu bar (top-right)
2. Click the icon to open the menu
3. Try the keyboard shortcuts:
   - `Option+Space` - Open action (currently just logs)
   - `Cmd+,` - Open Settings window
   - `Cmd+Q` - Quit application

## Building for Distribution

### Build everything:
```bash
npm run build
```

### Create macOS packages:
```bash
# Creates both DMG and ZIP
npm run package:mac

# Or individually:
npm run package:mac:dmg
npm run package:mac:zip
```

Output will be in the `release/` directory.

## Project Structure Overview

```
instructure-agent/
├── src/
│   ├── main/              # Electron main process (Node.js)
│   │   ├── index.ts       # Entry point, app lifecycle
│   │   ├── tray.ts        # Menu bar icon
│   │   ├── menu.ts        # Menu items and shortcuts
│   │   ├── settings-window.ts  # Settings window management
│   │   ├── shortcuts.ts   # Global keyboard shortcuts
│   │   ├── updater.ts     # Auto-updates
│   │   └── store.ts       # Settings storage (RxJS)
│   │
│   ├── renderer/          # React UI
│   │   ├── settings/      # Settings window
│   │   │   ├── index.html
│   │   │   ├── index.tsx
│   │   │   └── App.tsx    # Settings UI components
│   │   └── types.ts       # TypeScript types
│   │
│   ├── preload/           # IPC bridge (security layer)
│   │   └── settings-preload.ts
│   │
│   └── assets/
│       └── icons/         # App icons
│
├── build/                 # Build resources
│   ├── entitlements.mac.plist
│   └── (icon.icns - create this)
│
└── dist/                  # Compiled output (created on build)
```

## Common Tasks

### Modify the Menu
Edit `src/main/menu.ts` to add/remove menu items or change shortcuts.

### Change Settings Schema
1. Update `Settings` interface in `src/main/store.ts`
2. Update `Settings` interface in `src/renderer/types.ts`
3. Update UI in `src/renderer/settings/App.tsx`

### Add Global Shortcuts
Edit `src/main/shortcuts.ts` to register new global keyboard shortcuts.

### Customize Open Action
Edit the `handleOpen()` function in `src/main/index.ts` to implement what happens when user triggers the open action.

## Troubleshooting

### "Cannot find module" errors
```bash
npm install
npm run build:main
```

### Settings window shows blank/error
1. Ensure Vite dev server is running: `npm run dev:renderer`
2. Check it's accessible at http://localhost:5173
3. Check console for errors

### Tray icon not showing
1. Check `src/assets/icons/` contains icon files (even empty placeholders work)
2. Check console logs for errors
3. Try restarting Electron

### Global shortcuts not working
1. Check another app isn't using the same shortcut
2. Check console logs for registration errors
3. Try `Option+Shift+Space` or another combination

### TypeScript errors
```bash
# Check main process
npm run build:main

# Renderer process errors will show in Vite output
npm run dev:renderer
```

## Next Steps

1. **Implement the Open Action**: Edit `handleOpen()` in `src/main/index.ts`
2. **Add Custom Icons**: Replace placeholder icons in `src/assets/icons/`
3. **Configure Updates**: Set your update server URL in `package.json`
4. **Add Features**: Extend the menu, add more settings, create additional windows
5. **Code Signing**: Set up Apple Developer certificates for distribution

## Resources

- [Electron Documentation](https://www.electronjs.org/docs)
- [React Documentation](https://react.dev/)
- [RxJS Documentation](https://rxjs.dev/)
- [electron-builder](https://www.electron.build/)

## Getting Help

- Check the main `README.md` for detailed architecture info
- Review logs at `~/Library/Logs/instructure-agent/main.log`
- Check the console output when running in development mode
