docs: add user guide and example projects (#139)

New users were confused about which files they write vs. which Ralph
manages, and how PROMPT.md, specs/, and fix_plan.md relate to each other.

Added:
- docs/user-guide/ with quick start tutorial, file reference, and
  requirements writing guide
- examples/simple-cli-tool/ showing minimal Ralph configuration
- examples/rest-api/ demonstrating when to use specs/
- README section explaining Ralph files and their relationships

Also documents specs/stdlib/ purpose for reusable patterns.

examples/rest-api/README.md

@@ -0,0 +1,100 @@
+# Example: REST API with Specifications
+
+This example shows a medium-complexity Ralph configuration for a bookstore REST API. It demonstrates when and how to use the specs/ directory.
+
+## What This Example Demonstrates
+
+- **Focused PROMPT.md** - High-level goals and principles
+- **Detailed specs/api.md** - Endpoint specifications that are too detailed for PROMPT.md
+- **Structured fix_plan.md** - Tasks organized by feature area
+
+## Project Structure
+
+```
+rest-api/
+├── .ralph/
+│   ├── PROMPT.md         # Project vision and principles
+│   ├── fix_plan.md       # Implementation tasks
+│   └── specs/
+│       └── api.md        # Detailed API specifications
+├── .ralphrc              # Configuration (auto-generated)
+└── README.md             # This file
+```
+
+## Why This Example Uses specs/
+
+The PROMPT.md keeps things high-level:
+- What the API is for (bookstore inventory)
+- Technology stack (FastAPI, PostgreSQL)
+- Key principles (REST conventions, authentication)
+
+But the API needs detailed specifications that would clutter PROMPT.md:
+- Exact request/response formats
+- Validation rules
+- Error codes
+- Pagination behavior
+
+That's what `specs/api.md` is for.
+
+## How to Use This Example
+
+1. Copy this directory to a new location:
+   ```bash
+   cp -r examples/rest-api ~/my-bookstore-api
+   cd ~/my-bookstore-api
+   ```
+
+2. Initialize git and Python environment:
+   ```bash
+   git init
+   python -m venv venv
+   source venv/bin/activate
+   pip install fastapi uvicorn sqlalchemy pytest
+   ```
+
+3. Run Ralph:
+   ```bash
+   ralph --monitor
+   ```
+
+## Key Points
+
+### PROMPT.md Sets Direction
+
+PROMPT.md answers "what are we building and how?" without getting into implementation details.
+
+### specs/api.md Provides Details
+
+When you need to specify:
+- Exact endpoint paths and methods
+- Request/response schemas
+- Business rules and constraints
+- Error handling behavior
+
+These details help Ralph implement correctly on the first try.
+
+### fix_plan.md References specs/
+
+Notice how tasks reference the specification:
+```markdown
+- [ ] Implement book endpoints per specs/api.md
+```
+
+This tells Ralph where to find the detailed requirements.
+
+## When to Add More Specs
+
+Consider adding additional spec files for:
+- **specs/database.md** - Schema details, relationships, indexes
+- **specs/auth.md** - Token formats, permission rules, session handling
+- **specs/stdlib/errors.md** - Standard error response format
+- **specs/stdlib/pagination.md** - Pagination conventions
+
+## Comparison with Simple Example
+
+| Aspect | Simple CLI | REST API |
+|--------|-----------|----------|
+| Complexity | Low | Medium |
+| Uses specs/ | No | Yes |
+| PROMPT.md length | ~40 lines | ~30 lines |
+| Why | Self-contained | API contracts need detail |