### Quickstart Guide

Source: https://github.com/wyattowalsh/riso/blob/main/specs/007-graphql-api-scaffold/plan.md

Provides a developer onboarding document with installation instructions, first query examples, playground usage, DataLoader patterns, authentication setup, testing examples, performance tips, and common pitfalls.

```APIDOC
## Quickstart Guide

### Description
This guide is designed for developer onboarding. It covers essential steps to get started with the project, including installation, making your first query, using the GraphQL playground, understanding DataLoader patterns, setting up authentication, and best practices for testing and performance.

### Method
N/A (Documentation)

### Endpoint
N/A (Documentation)

### Parameters
N/A (Documentation)

### Request Example
N/A (Documentation)

### Response
#### Documentation Sections
- **Installation**: Instructions to set up the development environment.
- **First Query Example**: A basic example of a GraphQL query.
- **Playground Usage**: How to interact with the GraphQL API using a playground.
- **DataLoader Patterns**: Best practices for implementing DataLoaders.
- **Authentication Setup**: Steps to configure authentication.
- **Testing Examples**: Examples of how to test the API.
- **Performance Tips**: Advice for optimizing API performance.
- **Common Pitfalls**: Potential issues and how to avoid them.

#### Response Example
N/A (Documentation)
```

--------------------------------

### Install Dependencies and Initialize Database

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

This set of commands handles the initial setup of the project's dependencies and database. It includes installing NPM packages, generating necessary types (like Prisma client or Drizzle types), pushing the database schema, seeding the database with initial data, and launching the database studio for inspection.

```bash
# Install NPM dependencies
pnpm install

# Generate Prisma client (or Drizzle types)
pnpm generate

# Push database schema
pnpm db:push

# Seed database with fixtures (if enabled)
pnpm db:seed

# Verify database connection
pnpm db:studio  # Opens Prisma Studio
```

--------------------------------

### Start Development Server

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

This command starts the local development server, allowing you to see your application running in real-time. It typically watches for file changes and automatically reloads the application. The default URL is usually http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Install Prerequisites with Setup Script (Shell)

Source: https://github.com/wyattowalsh/riso/blob/main/web/public/docs/guides/quickstart.html

Installs necessary tooling like Python, Node.js, pnpm, and pre-commit. Supports dry-run, interactive installation, and CI environments with a GITHUB_TOKEN.

```shell
# Check what tools are installed (dry-run mode)
./scripts/setup/setup.sh
# Install missing tools (interactive)
./scripts/setup/setup.sh --install
# Or use the Make target
make bootstrap
```

```powershell
./scripts/setup/setup.ps1 -Install
```

```shell
# CI environments
./scripts/setup/setup.sh --install --yes
```

--------------------------------

### Verify Environment Setup

Source: https://github.com/wyattowalsh/riso/blob/main/specs/015-codegen-scaffolding-tools/quickstart.md

Confirms that all required Python dependencies for the code generation feature are correctly installed and accessible. It runs a simple Python command to import key libraries.

```bash
uv run python -c "import jinja2, typer, rich, merge3; print('All dependencies OK')"
```

--------------------------------

### Copy Environment Example to Local

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

This command copies the example environment file to a local file, which is then used to configure the application's environment variables. It's a crucial step before adding specific API keys and settings.

```bash
cp .env.example .env.local
```

--------------------------------

### Get Example by ID (Python)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Retrieves a specific example using its unique ID. Returns a 404 error if the example is not found in the in-memory storage.

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, field_validator
from uuid import uuid4
from datetime import datetime

app = FastAPI()

# In-memory storage for demo (replace with database in real apps)
_examples: dict[str, dict] = {}

# --- Model Definitions (extracted from separate files for context) ---
class ExampleCreateRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="Example name")
    value: int = Field(..., ge=0, description="Non-negative integer value")
    description: str | None = Field(None, max_length=500, description="Optional description")
    tags: list[str] | None = Field(None, max_length=10, description="Optional tags")

    @field_validator("name")
    @classmethod
    def name_must_not_be_whitespace(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Name cannot be whitespace only")
        return v.strip()

    @field_validator("tags")
    @classmethod
    def validate_tags(cls, v: list[str] | None) -> list[str] | None:
        if v is not None:
            for tag in v:
                if not 1 <= len(tag) <= 50:
                    raise ValueError("Each tag must be 1-50 characters")
        return v

class ExampleUpdateRequest(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=100)
    value: int | None = Field(None, ge=0)
    description: str | None = Field(None, max_length=500)
    tags: list[str] | None = Field(None, max_length=10)

class ExampleResponse(BaseModel):
    id: str
    name: str
    value: int
    description: str | None = None
    tags: list[str]
    created_at: str
    updated_at: str

# --- API Endpoints ---
@app.get("/{example_id}", response_model=ExampleResponse)
async def get_example(example_id: str):
    """Get a specific example by ID."""
    if example_id not in _examples:
        raise HTTPException(status_code=404, detail="Example not found")
    return _examples[example_id]

```

--------------------------------

### Install Dependencies and Run FastAPI Development Server

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Provides commands to install project dependencies, including FastAPI, using 'uv sync', and then start the FastAPI development server using 'uv run'. The server is configured to reload on changes, listen on all interfaces, and run on port 8000.

```bash
# Sync dependencies (including FastAPI)
uv sync --extra api

# Start the development server
uv run uvicorn {package_name}.api.main:app --reload --host 0.0.0.0 --port 8000

```

--------------------------------

### Install API Versioning Library

Source: https://github.com/wyattowalsh/riso/blob/main/specs/010-api-versioning-strategy/quickstart.md

Installs the API versioning library using `uv` for package management. Supports both published versions and development installations from source.

```bash
# Install the API versioning library (once published)
uv pip install api-versioning

# Or for development, install from source
cd api-versioning
uv pip install -e .
```

--------------------------------

### Check Development Environment Versions

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Verifies that Node.js, pnpm, and Copier are installed and meet the minimum required versions for the Riso SaaS Starter template.

```bash
node --version
pnpm --version
copier --version
```

--------------------------------

### Deploy to Vercel using Vercel CLI

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Instructions for deploying the project to Vercel. This involves installing the Vercel CLI, logging in, deploying the project, adding necessary environment variables, and finally deploying to production.

```bash
# Install Vercel CLI
pnpm install -g vercel

# Login
vercel login

# Deploy
vercel

# Add environment variables
vercel env add DATABASE_URL
vercel env add CLERK_SECRET_KEY
# ... (add all variables from .env.local)

# Deploy to production
vercel --prod
```

--------------------------------

### Create Example (Python)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Creates a new example entry. It generates a unique ID, timestamps the creation, and stores the example in memory. Requires an ExampleCreateRequest model.

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, field_validator
from uuid import uuid4
from datetime import datetime

app = FastAPI()

# In-memory storage for demo (replace with database in real apps)
_examples: dict[str, dict] = {}

# --- Model Definitions (extracted from separate files for context) ---
class ExampleCreateRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="Example name")
    value: int = Field(..., ge=0, description="Non-negative integer value")
    description: str | None = Field(None, max_length=500, description="Optional description")
    tags: list[str] | None = Field(None, max_length=10, description="Optional tags")

    @field_validator("name")
    @classmethod
    def name_must_not_be_whitespace(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Name cannot be whitespace only")
        return v.strip()

    @field_validator("tags")
    @classmethod
    def validate_tags(cls, v: list[str] | None) -> list[str] | None:
        if v is not None:
            for tag in v:
                if not 1 <= len(tag) <= 50:
                    raise ValueError("Each tag must be 1-50 characters")
        return v

class ExampleUpdateRequest(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=100)
    value: int | None = Field(None, ge=0)
    description: str | None = Field(None, max_length=500)
    tags: list[str] | None = Field(None, max_length=10)

class ExampleResponse(BaseModel):
    id: str
    name: str
    value: int
    description: str | None = None
    tags: list[str]
    created_at: str
    updated_at: str

# --- API Endpoints ---
@app.post("/", response_model=ExampleResponse, status_code=201)
async def create_example(request: ExampleCreateRequest):
    """Create a new example."""
    example_id = str(uuid4())
    now = datetime.utcnow().isoformat() + "Z"

    example = {
        "id": example_id,
        "name": request.name,
        "value": request.value,
        "description": request.description,
        "tags": request.tags or [],
        "created_at": now,
        "updated_at": now,
    }

    _examples[example_id] = example
    return example

```

--------------------------------

### Create Example

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Creates a new example with the provided details. Returns the created example upon success.

```APIDOC
## POST /

### Description
Create a new example.

### Method
POST

### Endpoint
/

### Request Body
- **name** (str) - Required - Example name (1-100 characters, not whitespace only).
- **value** (int) - Required - Non-negative integer value.
- **description** (str) - Optional - Description for the example (max 500 characters).
- **tags** (list[str]) - Optional - List of tags (max 10 tags, each 1-50 characters).

### Request Example
{
  "example": {
    "name": "New Example",
    "value": 200,
    "description": "A newly created example.",
    "tags": ["new", "test"]
  }
}

### Response
#### Success Response (201)
- **id** (str) - The unique identifier for the example.
- **name** (str) - The name of the example.
- **value** (int) - The integer value associated with the example.
- **description** (str) - An optional description for the example.
- **tags** (list[str]) - A list of tags associated with the example.
- **created_at** (str) - The timestamp when the example was created.
- **updated_at** (str) - The timestamp when the example was last updated.

#### Response Example
{
  "example": {
    "id": "f0e9d8c7-b6a5-4321-0987-fedcba098765",
    "name": "New Example",
    "value": 200,
    "description": "A newly created example.",
    "tags": ["new", "test"],
    "created_at": "2023-10-27T10:05:00Z",
    "updated_at": "2023-10-27T10:05:00Z"
  }
}
```

--------------------------------

### List Examples

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Retrieves a list of all examples with optional pagination. Defaults to a limit of 10 and offset of 0.

```APIDOC
## GET /

### Description
List all examples with pagination.

### Method
GET

### Endpoint
/

### Query Parameters
- **limit** (int) - Optional - The maximum number of examples to return.
- **offset** (int) - Optional - The number of examples to skip before returning results.

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the example.
- **name** (str) - The name of the example.
- **value** (int) - The integer value associated with the example.
- **description** (str) - An optional description for the example.
- **tags** (list[str]) - A list of tags associated with the example.
- **created_at** (str) - The timestamp when the example was created.
- **updated_at** (str) - The timestamp when the example was last updated.

#### Response Example
{
  "example": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "Example 1",
      "value": 100,
      "description": "This is the first example.",
      "tags": ["tag1", "tag2"],
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Update Example (Python)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Updates an existing example identified by its ID. Allows partial updates for name, value, description, and tags. Updates the 'updated_at' timestamp. Returns a 404 if the example is not found.

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, field_validator
from uuid import uuid4
from datetime import datetime

app = FastAPI()

# In-memory storage for demo (replace with database in real apps)
_examples: dict[str, dict] = {}

# --- Model Definitions (extracted from separate files for context) ---
class ExampleCreateRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="Example name")
    value: int = Field(..., ge=0, description="Non-negative integer value")
    description: str | None = Field(None, max_length=500, description="Optional description")
    tags: list[str] | None = Field(None, max_length=10, description="Optional tags")

    @field_validator("name")
    @classmethod
    def name_must_not_be_whitespace(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Name cannot be whitespace only")
        return v.strip()

    @field_validator("tags")
    @classmethod
    def validate_tags(cls, v: list[str] | None) -> list[str] | None:
        if v is not None:
            for tag in v:
                if not 1 <= len(tag) <= 50:
                    raise ValueError("Each tag must be 1-50 characters")
        return v

class ExampleUpdateRequest(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=100)
    value: int | None = Field(None, ge=0)
    description: str | None = Field(None, max_length=500)
    tags: list[str] | None = Field(None, max_length=10)

class ExampleResponse(BaseModel):
    id: str
    name: str
    value: int
    description: str | None = None
    tags: list[str]
    created_at: str
    updated_at: str

# --- API Endpoints ---
@app.put("/{example_id}", response_model=ExampleResponse)
async def update_example(example_id: str, request: ExampleUpdateRequest):
    """Update an existing example."""
    if example_id not in _examples:
        raise HTTPException(status_code=404, detail="Example not found")

    example = _examples[example_id]

    if request.name is not None:
        example["name"] = request.name
    if request.value is not None:
        example["value"] = request.value
    if request.description is not None:
        example["description"] = request.description
    if request.tags is not None:
        example["tags"] = request.tags

    example["updated_at"] = datetime.utcnow().isoformat() + "Z"

    return example

```

--------------------------------

### Generate SaaS App from Riso Template (Presets)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Generates a SaaS application using pre-configured stacks for faster setup, offering options like Vercel Starter, Edge-Optimized, All-in-One Platform, and Enterprise-Ready.

```bash
# Vercel Starter Stack (fastest setup, best DX)
copier copy --data saas_preset=vercel-starter gh:wyattowalsh/riso my-saas-app

# Edge-Optimized Stack (global edge, low cost)
copier copy --data saas_preset=edge-optimized gh:wyattowalsh/riso my-saas-app

# All-in-One Platform Stack (Supabase + Vercel)
copier copy --data saas_preset=all-in-one-platform gh:wyattowalsh/riso my-saas-app

# Enterprise-Ready Stack (SSO, SCIM, compliance)
copier copy --data saas_preset=enterprise-ready gh:wyattowalsh/riso my-saas-app
```

--------------------------------

### Setup Riso Project with Git Clone and Dependency Installation

Source: https://github.com/wyattowalsh/riso/blob/main/AGENTS.md

This snippet demonstrates the initial steps to set up the Riso project. It involves cloning the repository, navigating into the project directory, synchronizing all dependencies including extras, installing pre-commit hooks, and verifying the setup by running tests.

```bash
git clone https://github.com/wyattowalsh/riso.git
cd riso

uv sync --all-extras

uv run pre-commit install --install-hooks

uv run pytest tests/ -x -q
```

--------------------------------

### Get Example by ID

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Retrieves a specific example using its unique identifier.

```APIDOC
## GET /{example_id}

### Description
Get a specific example by ID.

### Method
GET

### Endpoint
/{example_id}

### Path Parameters
- **example_id** (str) - Required - The unique identifier of the example to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the example.
- **name** (str) - The name of the example.
- **value** (int) - The integer value associated with the example.
- **description** (str) - An optional description for the example.
- **tags** (list[str]) - A list of tags associated with the example.
- **created_at** (str) - The timestamp when the example was created.
- **updated_at** (str) - The timestamp when the example was last updated.

#### Response Example
{
  "example": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "Example 1",
    "value": 100,
    "description": "This is the first example.",
    "tags": ["tag1", "tag2"],
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z"
  }
}

#### Error Response (404)
- **detail** (str) - "Example not found"

#### Error Response Example
{
  "detail": "Example not found"
}
```

--------------------------------

### Start Riso Development Server with Uvicorn

Source: https://github.com/wyattowalsh/riso/blob/main/specs/008-websockets-scaffold/quickstart.md

Instructions to install dependencies and run the Riso development server using Uvicorn, which supports WebSocket protocol upgrades. The server will be accessible at http://0.0.0.0:8000.

```bash
# Install dependencies
uv sync

# Run with uvicorn (supports WebSocket protocol upgrade)
uv run uvicorn my_app.api.main:app --host 0.0.0.0 --port 8000 --reload

# Server should report:
# INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
# INFO:     Application startup complete.
```

--------------------------------

### Run Baseline Quickstart Validation (Python)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/004-github-actions-workflows/tasks.md

Executes a Python script to perform baseline validation of the quickstart guide. This is a crucial step for ensuring the initial setup and configuration are correct.

```bash
python scripts/ci/run_baseline_quickstart.py
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

This section shows how to populate the `.env.local` file with necessary API keys and connection strings for various services like database, authentication, billing, email, jobs, analytics, AI, and observability. It ensures the application can connect to and utilize these external services.

```bash
# Database
DATABASE_URL="postgres://user:pass@host.neon.tech/db"

# Auth (Clerk)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# Billing (Stripe)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Email (Resend)
RESEND_API_KEY="re_..."

# Jobs (Trigger.dev)
TRIGGER_API_KEY="trigger_..."

# Analytics (PostHog)
NEXT_PUBLIC_POSTHOG_KEY="phc_..."
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"

# AI (OpenAI)
OPENAI_API_KEY="sk-..."

# Observability
SENTRY_DSN="https://...@sentry.io/..."
DD_API_KEY="..." # Datadog
```

--------------------------------

### Deploy to Cloudflare using Wrangler CLI

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Steps for deploying the project to Cloudflare using the Wrangler CLI. This includes installing Wrangler, logging in, adding secrets, and deploying the application.

```bash
# Install Wrangler CLI
pnpm install -g wrangler

# Login
wrangler login

# Add secrets
wrangler secret put DATABASE_URL
wrangler secret put CLERK_SECRET_KEY
# ... (add all secrets)

# Deploy
wrangler deploy
```

--------------------------------

### Riso Setup Log Example (Log Format)

Source: https://github.com/wyattowalsh/riso/blob/main/scripts/setup/README.md

An example of the log file generated by the Riso setup script, showing the header information and detailed log entries in a human-readable format.

```log
# Riso Setup Log - setup
# Started: 2025-12-24T20:51:54Z
# Platform: Darwin 25.3.0 arm64
# Shell: /opt/homebrew/bin/zsh

[2025-12-24T20:51:54Z] INFO    === Setup started ===
[2025-12-24T20:51:54Z] INFO    Mode: check_only=0 install=0 yes=0
[2025-12-24T20:51:55Z] INFO    All tools present
```

--------------------------------

### List Examples with Pagination (Python)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Retrieves a list of examples with support for pagination using limit and offset parameters. It accesses data from an in-memory dictionary.

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, field_validator
from uuid import uuid4
from datetime import datetime

app = FastAPI()

# In-memory storage for demo (replace with database in real apps)
_examples: dict[str, dict] = {}

# --- Model Definitions (extracted from separate files for context) ---
class ExampleCreateRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="Example name")
    value: int = Field(..., ge=0, description="Non-negative integer value")
    description: str | None = Field(None, max_length=500, description="Optional description")
    tags: list[str] | None = Field(None, max_length=10, description="Optional tags")

    @field_validator("name")
    @classmethod
    def name_must_not_be_whitespace(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Name cannot be whitespace only")
        return v.strip()

    @field_validator("tags")
    @classmethod
    def validate_tags(cls, v: list[str] | None) -> list[str] | None:
        if v is not None:
            for tag in v:
                if not 1 <= len(tag) <= 50:
                    raise ValueError("Each tag must be 1-50 characters")
        return v

class ExampleUpdateRequest(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=100)
    value: int | None = Field(None, ge=0)
    description: str | None = Field(None, max_length=500)
    tags: list[str] | None = Field(None, max_length=10)

class ExampleResponse(BaseModel):
    id: str
    name: str
    value: int
    description: str | None = None
    tags: list[str]
    created_at: str
    updated_at: str

# --- API Endpoints ---
@app.get("/", response_model=list[ExampleResponse])
async def list_examples(limit: int = 10, offset: int = 0):
    """List all examples with pagination."""
    examples = list(_examples.values())
    return examples[offset : offset + limit]

```

--------------------------------

### Riso Setup Script - Windows PowerShell Installation

Source: https://github.com/wyattowalsh/riso/blob/main/scripts/setup/README.md

Shows how to run the Riso setup script using PowerShell on Windows. It includes setting the execution policy and performing installation with confirmation.

```powershell
# Run from PowerShell with admin rights (if needed for installation)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Check and install
.\scripts\setup\setup.ps1 -Install -Yes
```

--------------------------------

### Install mise for Toolchain Management

Source: https://github.com/wyattowalsh/riso/blob/main/specs/002-docs-template-expansion/quickstart.md

Installs 'mise', a tool for managing multiple language versions. Ensure 'auto_install = true' is set in '.mise.toml' to automatically provision Node.js 20 LTS and pnpm 8.

```bash
curl -LsSf https://mise.jdx.dev/install.sh | sh
# Ensure auto_install = true in .mise.toml
```

--------------------------------

### Validate FastAPI Endpoints with Curl

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Illustrates how to test various API endpoints of a running FastAPI application using curl. It includes commands to test the health check, root endpoint, create an example via POST request, list examples via GET request, and access the interactive Swagger UI documentation.

```bash
# Test health check
curl http://localhost:8000/health/
# Expected: {"status":"healthy","version":"0.1.0","timestamp":"..."}

# Test root endpoint
curl http://localhost:8000/
# Expected: {"message":"Welcome to...","version":"0.1.0","docs":"/docs"}

# Create an example
curl -X POST http://localhost:8000/examples/ \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","value":42}'
# Expected: 201 Created with example data

# List examples
curl http://localhost:8000/examples/
# Expected: Array with created example

# Access interactive docs
open http://localhost:8000/docs
# Expected: Swagger UI with all endpoints documented

```

--------------------------------

### Riso Setup Script - Basic Workflow (Bash)

Source: https://github.com/wyattowalsh/riso/blob/main/scripts/setup/README.md

Demonstrates the basic workflow for using the Riso setup script in Bash. It covers checking tool status, installing missing tools, and verifying the installation.

```bash
# 1. Check current status
./scripts/setup/setup.sh

# Example output:
# Tool Status
# Tool            Version              Status
# ----            -------              ------
# python3         3.14.2               ✓ OK
# uv              0.8.22               ✓ OK
# node            25.2.1               ✓ OK
# pnpm            9.15.0               ✓ OK
# pre-commit      4.3.0                ✓ OK
# actionlint      1.7.9                ✓ OK

# 2. Install missing tools
./scripts/setup/setup.sh --install

# 3. Verify installation
./scripts/setup/setup.sh --check-only && echo "All tools ready!"
```

--------------------------------

### Configuration Files (Environment, Package, TSConfig)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/FINAL_SESSION_SUMMARY.md

Core configuration files for the project. Includes environment variable validation (66 variables), a dynamic package.json (~50 packages), TypeScript configuration, and an environment template.

```json
lib/env.ts.jinja - Environment validation (66 variables)
package.json.jinja - Dynamic package.json (~50 packages)
tsconfig.json.jinja - TypeScript configuration
.env.example.jinja - Environment template
```

--------------------------------

### Generate SaaS App from Riso Template (Interactive)

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Clones the Riso template and guides the user through interactive prompts to configure their SaaS application, including runtime, infrastructure, and observability settings.

```bash
# Clone or download the Riso template
copier copy gh:wyattowalsh/riso my-saas-app

# Navigate to project
cd my-saas-app
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/wyattowalsh/riso/blob/main/specs/015-codegen-scaffolding-tools/quickstart.md

Installs core and development dependencies for the code generation feature using the uv package manager. Ensures necessary libraries like Jinja2, Typer, and pytest are available.

```bash
cd /workspaces/riso
uv add jinja2>=3.1.5 typer>=0.20.0 rich>=13.0.0 merge3>=0.0.13 gitpython>=3.1.40
uv add --dev pytest>=7.4.0 pytest-cov>=4.1.0 mypy>=1.7.0
```

--------------------------------

### Delete Example

Source: https://github.com/wyattowalsh/riso/blob/main/specs/006-fastapi-api-scaffold/quickstart.md

Deletes a specific example using its unique identifier.

```APIDOC
## DELETE /{example_id}

### Description
Delete an example.

### Method
DELETE

### Endpoint
/{example_id}

### Path Parameters
- **example_id** (str) - Required - The unique identifier of the example to delete.

### Response
#### Success Response (204)
No content is returned upon successful deletion.

#### Error Response (404)
- **detail** (str) - "Example not found"

#### Error Response Example
{
  "detail": "Example not found"
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/wyattowalsh/riso/blob/main/web/public/docs/_sources/guides/quickstart.md.txt

Installs required tooling for the Riso project, including Python, Node.js, and other development dependencies. Supports interactive installation and CI environments.

```bash
./scripts/setup/setup.sh
./scripts/setup/setup.sh --install
make bootstrap
```

--------------------------------

### Test Email Sending and Analytics

Source: https://github.com/wyattowalsh/riso/blob/main/specs/012-saas-starter/quickstart.md

Guides on testing email sending functionality by sending a test email to a specified address and verifying analytics tracking by checking for a 'page_view' event in PostHog after visiting the dashboard.

```bash
# Send test email
pnpm email:test --to your@email.com

# Check inbox for email

# Visit dashboard → should see event tracked in PostHog
# Event: page_view, user_id: <your-user-id>
```