# Quick start: your first end-to-end change

This walks you through one complete "let the AI change my code for me" loop with the fewest possible steps. By the end you'll have a feel for the core concepts — apps, chats, tasks, main versions — and the rest of the docs will read much faster.

> About 5 minutes. Every link below jumps straight to the matching page, so you can try things as you read and come back.

## The mental model

```
App (your code repository + a resident agent)
   │
   ├── App main version   ← the default branch (production releases come from here)
   │
   ├── Chat              ← a lightweight one-off conversation: ask, try a change
   └── Task              ← goal-driven work with a plan; runs longer and steadier
```

The short version:

- **App** = "the project you want the AI to work on". Each app is bound to a code repository and an agent.
- **Chat** = a one-on-one conversation. The AI works on one thing at a time, so chats queue up **one after another**. Good for "let's just try it".
- **Task** = a group chat. Several chats can push the **same** larger piece of work forward **in parallel**, and everything is merged back to the default branch once they're all done.

## Step 1 — Create an app with "AI recommendation"

The easiest way in: describe what you want, and the platform picks an open-source project and forks it as the foundation for your app. Repository and infrastructure are set up in one go.

Open [Apps](#/apps), click **+ Add app** in the top right. A picker opens with **"AI-recommended open-source project"** already selected (it carries a *Recommended* badge):

1. Keep **"AI-recommended open-source project"** selected
2. Click **Start conversation**
3. In the chat that opens, describe what you need in one sentence — e.g. "I want a to-do web app that supports multiple people working together" — and press Ctrl+Enter
4. The AI comes back with 3–5 candidate projects, each with a summary, why it fits, and the risks worth knowing about
5. Pick the best fit and click **Create app from this project**. The platform forks the repository and initialises the configuration.

When the dialog closes you'll see "App creation started — wait for the status to become *Success*". Back on the app list there's a new row whose status goes from `Creating` to `Success`. Once it's successful you can start using it.

> Already have a GitHub repository in mind? Choose **"From an open-source project"** and paste the URL. Want full control? Choose **"Custom"** and walk the full wizard. If you're new, we strongly suggest doing the AI-recommendation path end to end at least once.
>
> Stuck on anything along the way? Open [Chat](#/chats) — the app dropdown defaults to **"default"**, the general-purpose assistant. Just ask it.

## Step 2 — Try a small change in a chat

Open [Chat](#/chats):

1. In the input box at the bottom right, select the **app** you just created
2. Type a one-line request, e.g. "Change the homepage title to 'Hello world'", and press **Ctrl + Enter**
3. A new chat is created automatically; it appears on the left and its status moves from `Waiting` to `Running…`
4. The current version **does not stream output**. The result appears on the right all at once when the run finishes; while it's running you'll only see a bouncing ellipsis
5. When it's done, click **Preview** to see the result. Happy with it? Click **Merge into app main version**. Not happy? Keep asking for changes in the same chat.

That's the fastest development loop available.

## Step 3 — Promote ongoing work to a task

For something bigger — "refactor the whole login module", say — use a task instead:

1. Open [Tasks](#/tasks) and click **+ New task**
2. Fill in the title, description and owning app, then save
3. The task card shows up in the list. Open it to find its chats, change history and merge buttons
4. A task can be **suspended** mid-flight and resumed whenever you're ready

`04-chats.md` covers the task-versus-chat boundary in detail.

## Step 4 — Finish up: merge, then release to production

Finishing the run is only the first half. These two steps are what make a change real:

1. **Merge the code**: in the chat or task detail, click *Merge into app main version* (inside a task there's also *Merge into task main version* for incremental merges). Only after merging does the change land on the default branch.
2. **Release to production**: go to [Apps](#/apps) and click **Release** in the app's "Actions" column to open the *Release details* page. **You don't have to pick a commit by hand.** Either route works:
   - **Release directly**: select the app in the "App" filter at the top, click **Release to production** in the top right, write a release note, and submit. The platform triggers a new production release from the current state of the default branch.
   - **Promote an existing build**: in the table below, find a **test** environment record with status `Success` and both Task ID and Chat ID equal to `0` (these are built automatically after a merge to the default branch), then click **Go live** at the end of the row to switch that exact build to production.

   Code on the default branch **only takes effect once it has been released** — until then it's just a commit in the repository.

## What to read next

- Want to understand what "main version" really means? See `01-concepts.md`
- Want to go deeper on app configuration? See `02-apps.md`
- Want the chat-versus-task boundary? See `04-chats.md`