# RSpade Framework - Quick Start Guide

## Installation

### Clone the Repository

Clone the RSpade project with the framework submodule:

```bash
git clone --recurse-submodules ssh://git@privategit.hanson.xyz:3322/brianhansonxyz/rspade_project.git /path/to/project
cd /path/to/project
```

**Alternative method** (clone then initialize submodules):

```bash
git clone ssh://git@privategit.hanson.xyz:3322/brianhansonxyz/rspade_project.git /path/to/project
cd /path/to/project
git submodule update --init --recursive
```

The `--recurse-submodules` flag automatically initializes and clones the `system` directory, which contains the RSpade framework.

### Initial Setup

1. **Copy environment configuration:**
   ```bash
   cp .env.dist .env
   ```

2. **Configure your database** in `.env`:
   ```
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=your_database
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   ```

3. **Install dependencies:**
   ```bash
   cd system
   composer install
   npm install
   ```

4. **Generate application key:**
   ```bash
   php artisan key:generate
   ```

5. **Run migrations:**
   ```bash
   php artisan migrate
   ```

6. **Build the manifest:**
   ```bash
   php artisan rsx:manifest:build
   ```

### Updating the Framework

The framework is managed as a git submodule in the `system` directory. To pull framework updates:

```bash
php artisan rsx:framework:pull
```

This command:
- Fetches updates from the upstream framework repository
- Applies updates while preserving your application code in `./rsx`
- Rebuilds manifests and bundles automatically

**Note**: The `system` submodule is preconfigured with both `origin` and `rspade_upstream` remotes pointing to the framework repository. The `rsx:framework:pull` command uses `rspade_upstream` to check for and apply updates.

## Your First Module

Create a simple module to verify everything works:

```bash
php artisan rsx:app:module:create welcome
```

This creates:
- `/rsx/app/welcome/welcome_controller.php` - Controller with routes
- `/rsx/app/welcome/welcome_view.blade.php` - Blade template
- `/rsx/app/welcome/welcome.js` - JavaScript class
- `/rsx/app/welcome/welcome.scss` - Styles

Visit `http://your-domain/welcome` to see your new module.

## Essential Commands

### Development

```bash
php artisan rsx:check              # Check code quality
php artisan rsx:routes             # View all routes
php artisan rsx:debug /route       # Test a route
php artisan rsx:manifest:build     # Rebuild manifest
```

### Creating Structure

```bash
php artisan rsx:app:module:create <name>              # Create new module
php artisan rsx:app:module:feature:create <m> <f>     # Add feature to module
php artisan rsx:app:component:create --name=<name>    # Create jqhtml component
```

### Database

```bash
php artisan make:migration:safe create_table_name     # Create migration
php artisan migrate                                    # Run migrations
php artisan db:query "SELECT * FROM users" --json     # Query database
```

## Next Steps

- Read `./docs/CLAUDE.dist.md` for comprehensive framework documentation
- Explore the demo module at `/rsx/app/demo/`
- Review `./docs/framework_divergences.md` to understand how RSpade differs from standard Laravel

## Getting Help

Run any command with `--help` to see detailed usage:

```bash
php artisan rsx:app:module:create --help
```

Use the man system for detailed documentation on specific topics:

```bash
php artisan rsx:man                    # List all topics
php artisan rsx:man routing            # View routing documentation
php artisan rsx:man jqhtml             # View jqhtml component documentation
```