QUICKSTART.md

# Quick Start Guide

## Initial Setup (First Time)

1. **Run the setup script:**
   ```bash
   bash setup.sh
   ```

2. **Configure your credentials:**
   Edit `.env` file with your credentials:
   - Get HuggingFace token from: https://huggingface.co/settings/tokens
   - Get Anthropic API key from: https://console.anthropic.com/

3. **Update space names:**
   Edit `config.yaml` to set your HuggingFace space names

## Using the Web Interface

```bash
streamlit run app.py
```

Then open your browser to the URL shown (usually http://localhost:8501)

### Web Interface Features:

- **Dashboard**: Overview of your spaces and recent activity
- **AI Agent**: Chat with Claude to get help with code and file management
- **File Manager**: Browse, upload, and manage files
- **Space Sync**: Synchronize files to HuggingFace Spaces
- **Audit & Archive**: Create file inventories and compressed archives

## Using the Command Line

### Run File Audit
```bash
python automation.py audit
```
Creates `inventory.json` and `genesis_archive_*.tar.gz`

### Sync All Configured Spaces
```bash
python automation.py sync
```
Uploads files to all spaces with `auto_sync: true`

### Sync Specific Space
```bash
python automation.py sync-space --space vamguard-titan
```

### Create Backup
```bash
python automation.py backup
```
Backs up everything to mapping-and-inventory space

### Full Automation
```bash
python automation.py full
```
Runs: audit → sync all → backup

## GitHub Actions Setup

For automated syncing via GitHub Actions:

1. **Add secrets to your GitHub repository:**
   - Go to Settings → Secrets and variables → Actions
   - Add: `HF_TOKEN`, `HF_USERNAME`, `ANTHROPIC_API_KEY`

2. **Push to trigger:**
   ```bash
   git add .
   git commit -m "Initial setup"
   git push
   ```

3. **Manual trigger:**
   - Go to Actions tab on GitHub
   - Select "HuggingFace Space Sync" workflow
   - Click "Run workflow"

## Common Tasks

### Create a New HuggingFace Space

**Via Web UI:**
1. Open app: `streamlit run app.py`
2. Navigate to "Space Sync" → "Create Space" tab
3. Enter space name and click "Create Space"

**Via Python:**
```python
from hf_space_sync import HFSpaceSync

sync = HFSpaceSync()
sync.create_space("my-new-space", "streamlit", private=False)
```

### Upload Files to a Space

```python
from hf_space_sync import HFSpaceSync

sync = HFSpaceSync()
sync.upload_files("vamguard-titan", "app.py", commit_message="Update app")
```

### Ask the AI Agent for Help

**Via Web UI:**
1. Open app: `streamlit run app.py`
2. Go to "AI Agent" page
3. Type your question: "How do I organize my Python files?"

**Via Python:**
```python
from app import AIAgent

agent = AIAgent()
response = agent.process_request("Help me sync files to HuggingFace")
print(response)
```

## Troubleshooting

**"Module not found" errors:**
```bash
source venv/bin/activate  # Activate virtual environment
pip install -r requirements.txt
```

**HuggingFace authentication errors:**
- Check `.env` file has correct `HF_TOKEN`
- Verify token at https://huggingface.co/settings/tokens
- Ensure token has write permissions

**AI Agent not responding:**
- Verify `ANTHROPIC_API_KEY` in `.env`
- Check API key at https://console.anthropic.com/
- Ensure you have API credits

## File Locations

- **Configuration**: `config.yaml`
- **Environment**: `.env`
- **Logs**: `automation_log_*.txt`
- **Reports**: `automation_report_*.json`
- **Inventories**: `inventory.json`
- **Archives**: `genesis_archive_*.tar.gz`

## Getting Help

- Check the full README.md for detailed documentation
- Review logs in `automation_log_*.txt`
- Open an issue on GitHub
- Use the AI Agent in the web interface

## Next Steps

1. Customize `config.yaml` for your needs
2. Add more spaces to the configuration
3. Set up GitHub Actions for automation
4. Explore the AI Agent capabilities
5. Create scheduled backups

Happy coding! 🚀