rspade_system/docs/framework_upstream.md

# Framework Upstream Synchronization

This document explains how to keep your RSpade project synchronized with framework updates.

## Overview

When you create a new project from the RSpade framework template, you get your own Git repository for your project-specific code. However, you'll also want to pull in framework updates and improvements over time. This is managed through Git's upstream remote functionality.

## Initial Setup

When starting a new project from this template:

1. **Clone/fork this template** to create your project repository
2. **Change the origin** to your project's repository:
   ```bash
   git remote set-url origin git@your-server:your-project.git
   ```
3. **Setup framework upstream**:
   ```bash
   bin/framework-upstream setup
   ```

This configures `ssh://git@192.168.0.3:3322/brianhansonxyz/rspade-publish.git` as the `framework-upstream` remote.

## Workflow

### Check for Updates

Check if framework updates are available:
```bash
bin/framework-upstream status
```

This shows:
- Whether you're up to date with the framework
- How many commits ahead/behind you are
- If your project has diverged from the framework

### Pull Framework Updates

To merge framework updates into your project:
```bash
bin/framework-upstream pull
```

This will:
1. Fetch the latest framework changes
2. Attempt to merge them into your current branch
3. Report any conflicts that need manual resolution

### View Framework Changes

See recent framework commits:
```bash
bin/framework-upstream logs
```

View differences between your project and the framework:
```bash
bin/framework-upstream diff
```

## Handling Conflicts

When pulling framework updates, you may encounter merge conflicts if you've modified framework files. This is normal and expected.

### Common Conflict Areas

- `CLAUDE.md` - If you've customized AI directives
- `config/` files - If you've modified framework configuration
- `.gitignore` - If you've added project-specific ignores

### Resolution Strategy

1. **Review the conflicts** carefully
2. **Keep your project-specific changes** where appropriate
3. **Accept framework improvements** where they don't conflict with your customizations
4. **Test thoroughly** after resolving conflicts

### Conflict Commands

During a merge conflict:
```bash
# See which files have conflicts
git status

# After resolving conflicts in a file
git add <resolved-file>

# Complete the merge
git commit

# Or abort if needed
git merge --abort
```

## Best Practices

### 1. Minimize Framework Modifications

- Work primarily in `/rsx/` for your application code
- Avoid modifying `/app/RSpade/` framework files
- Use configuration files for customization when possible

### 2. Regular Updates

- Check for updates weekly: `bin/framework-upstream status`
- Pull updates regularly to avoid large divergences
- Test thoroughly after each update

### 3. Document Customizations

If you must modify framework files:
- Document the changes in your project README
- Consider if the change should be contributed back to the framework
- Keep modifications minimal and well-commented

### 4. Commit Before Updating

Always commit your changes before pulling framework updates:
```bash
git add -A
git commit -m "Save work before framework update"
bin/framework-upstream pull
```

## Framework Update Types

### Patch Updates
- Bug fixes
- Security patches
- Documentation improvements
- Usually safe to pull immediately

### Feature Updates
- New framework capabilities
- New helper functions
- Enhanced commands
- Review changes before pulling

### Breaking Changes
- Rare but possible
- Will be documented in framework commits
- May require code changes in your project

## Troubleshooting

### "Not in a git repository"
Ensure you're in your project root directory

### "Upstream not configured"
Run: `bin/framework-upstream setup`

### "You have uncommitted changes"
Commit or stash your changes before pulling:
```bash
git add -A && git commit -m "WIP"
# or
git stash
```

### Merge conflicts persist
Consider:
1. Understanding what changed in the framework
2. Reviewing your local modifications
3. Potentially refactoring to reduce conflicts

## Manual Git Commands

The `bin/framework-upstream` script automates these Git commands:

```bash
# Add upstream remote manually
git remote add framework-upstream ssh://git@192.168.0.3:3322/brianhansonxyz/rspade-publish.git

# Fetch updates
git fetch framework-upstream

# Merge updates
git merge framework-upstream/master

# Check status
git log HEAD..framework-upstream/master --oneline
```

## Contributing Back

If you make improvements that would benefit all RSpade projects:
1. Consider contributing them back to the framework
2. Create a clean branch with just the framework improvements
3. Submit a pull request to the framework repository

## Support

For framework update issues:
- Check the framework repository for announcements
- Review recent commits for breaking changes
- Test in a development environment first