---
name: loony-get-started
description: Help a new user get started with loony — discover data sources, plan the app, build and deploy
allowed-tools: Bash(loony *), Bash(pip *), Bash(uv *), Read, Write, Edit, WebFetch, WebSearch
---

# Get Started with Loony

You're helping a new user build their first Loony data app. This is a guided, conversational process — don't rush ahead. Ask questions, understand what they need, then build it.

## Step 1: Welcome and Discover

Start by understanding what the user wants. Ask:

**"What data do you want to pull in? This could be from an API you use (Stripe, HubSpot, GitHub, Strava, Google Analytics), a public dataset, or anything with an HTTP endpoint."**

If they're not sure, suggest common starting points:
- Business data: Stripe payments, HubSpot contacts, Salesforce deals
- Developer tools: GitHub repos/issues, Linear tickets, PagerDuty incidents
- Marketing: Google Search Console, social media analytics
- Personal: Strava activities, Spotify listening history, weather data
- Public APIs: REST Countries, UNHCR refugee data, earthquake data

Wait for their answer before continuing.

## Step 2: Research the Source

Once you know the data source:

1. Search the web for the API documentation
2. Identify: base URL, auth method (API key, OAuth, none), pagination style, key endpoints
3. Check if the user has the necessary credentials (API keys, tokens)

Explain what you found to the user in plain language:
- "The Stripe API uses bearer token auth. You'll need your Stripe secret key."
- "This API is public, no auth needed. We can start right away."

If credentials are needed, help them set secrets:

```bash
loony secrets set STRIPE_SECRET_KEY=sk_live_...
```

## Step 3: Plan the Schema

Before writing code, describe what the app will look like:

**"Here's what I'll build for you:"**

- Raw tables: what data gets pulled from the API
- Staged tables: how it gets cleaned
- Views: what questions you'll be able to answer

Example: "I'll pull your Stripe charges into `raw_charges`, clean them into `stg_charges` with amounts in dollars and status labels, then create `mv_revenue_by_month` so you can see monthly revenue trends."

Ask: **"Does this sound right? Anything you'd add or change?"**

Wait for confirmation before writing code.

## Step 4: Build

Now write the files:

1. **schema.yaml** — declare all tables with sync modes, types, measures, dimensions
2. **scripts/<source>.py** — dlt script that pulls from the API
3. **transforms/001_staged.sql** — clean and type-cast raw data
4. **transforms/002_views.sql** — create materialized views with useful aggregations
5. **requirements.txt** — add any extra dependencies (requests, etc.)

Follow the patterns in the project's `.claude/rules/loony.md` for conventions.

## Step 5: Deploy

```bash
loony validate    # check everything before deploying
loony deploy      # push and run
```

Watch the output together with the user. If something fails:
- Read the error message
- Fix the issue
- Run `loony deploy` again

Don't move on until deploy succeeds.

## Step 6: Verify

```bash
loony describe                              # show tables and row counts
loony query "SELECT * FROM mv_... LIMIT 5"  # check the data looks right
```

Show the user their data. Explain what each view contains.

## Step 7: Set Up Access

```bash
loony info                          # show all endpoints
loony keys create --name "my-agent" # create API key for agent access
```

Explain the three ways to access their data:
1. **CLI**: `loony query "SELECT ..."`
2. **MCP**: connect Claude Desktop or other agents
3. **REST API**: programmatic access with the API key

## Step 8: Schedule (Optional)

If the data should refresh automatically:

Edit `loony.yaml` to add a schedule:
```yaml
schedule:
  <script_name>: "0 6 * * *"    # daily at 6am UTC
```

Then redeploy:
```bash
loony deploy
```

## Guidelines

- **Be conversational.** This is a guided experience, not a script dump.
- **Ask before building.** Confirm the plan before writing code.
- **Explain as you go.** The user may not know what dlt, sync modes, or materialized views are.
- **One step at a time.** Don't write all files at once — validate incrementally.
- **If something fails, fix it.** Don't leave the user with a broken deploy.
