rspade_system/app/RSpade/man/CLAUDE.md

RSX Framework Manual Pages

Documentation Philosophy

These manual pages follow traditional Unix man page conventions from the late 1990s:

• Plain text format - No fancy formatting, boxes, or special characters
• Simple indentation - Code examples use 4-space indentation
• Readable and copyable - Easy to copy/paste examples
• Traditional sections - NAME, SYNOPSIS, DESCRIPTION, etc.

Writing Style Requirements

Format

• Use plain ASCII text only
• Code examples indented with 4 spaces
• No box drawing characters (└─┘│┌┐)
• No special Unicode symbols
• Section headers in ALL CAPS
• Subsection headers in Title Case

Content Requirements

Each man page must include:

1. General introduction - Explain what the RSX feature is and its purpose
2. RSX philosophy - How it simplifies development compared to standard approaches
3. Laravel differences - Explicitly note how RSX differs from Laravel equivalents
4. Practical examples - Real-world usage patterns from actual RSX applications
5. Common pitfalls - What mistakes developers might make

RSX vs Laravel Context

Always explain how RSX features differ from their Laravel counterparts:

• Path-agnostic class loading vs PSR-4 autoloading
• Manifest-based discovery vs service provider registration
• Static controller methods vs instance methods with DI
• Unified bundle system vs mix/vite configuration
• Automatic route discovery vs manual route files

Manual Page Sections

Standard sections in order:

NAME
    Component name and one-line description

SYNOPSIS
    Quick usage examples showing the most common use case

DESCRIPTION
    Overview of the component, its philosophy, and how it differs from Laravel

BASIC USAGE
    Step-by-step introduction to using the feature

API REFERENCE
    Detailed method/function documentation

EXAMPLES
    Practical, real-world code examples

RSX VS LARAVEL
    Explicit comparison with Laravel equivalents

TROUBLESHOOTING
    Common errors and their solutions

SEE ALSO
    Related manual pages

File Naming

• Use lowercase with underscores: manifest_api.txt
• Extensions: Always .txt for man pages
• No special characters or spaces

Example Introduction Template

DESCRIPTION
    The RSX [feature] provides [what it does] through [how it works].
    Unlike Laravel's [equivalent], which requires [Laravel approach],
    RSX automatically [RSX approach] without any configuration.

    This path-agnostic approach means developers never need to worry
    about [common Laravel pain point]. The framework handles all
    [technical detail] transparently.

    Key differences from Laravel:
    - Laravel: [how Laravel does it]
    - RSX: [how RSX does it]

    Benefits:
    - No [configuration/boilerplate] required
    - Automatic [feature]
    - Works with [use case]

Testing Documentation

After writing or updating a man page:

1. Test with php artisan rsx:man [topic]
2. Verify plain text output (no special characters)
3. Ensure code examples are properly indented
4. Confirm examples can be copy/pasted directly

Future Documentation Topics

Planned manual pages to create:

• model.txt - ORM with enum constants and Ajax fetch
• auth.txt - Session-based authentication (no JWT)
• testing.txt - RSX test framework
• ajax.txt - Internal API system with auto-generated stubs
• main.txt - Application-wide middleware hooks
• migration.txt - Forward-only database migrations