# Apps and the app main version

This page goes deep on apps and app main versions — everything chats and tasks build on.

## Where do I find my apps?

Open [Apps](#/apps) and you'll get a table with one row per app. The columns you'll use:

| Column | Meaning |
|--------|---------|
| ID | the app's unique number, globally unique across users |
| Name | whatever readable name you gave it |
| Status | where the app is right now — `Creating` / `Creation failed` / `Updating` / `Success` (see below). Click the badge for creation details |
| Links | open the test or production environment |

What the statuses mean:

| Status | Meaning |
|--------|---------|
| `Creating` | the platform is initialising (repository, database, default deployment) — just wait |
| `Creation failed` | something went wrong during initialisation; click the badge for the specific failure |
| `Updating` | configuration is being finalised asynchronously or redeployed; it'll come back on its own |
| `Success` | the app is ready to use |

## Adding an app: two routes

Click **+ Add app** in the top right and a picker opens.

### Route A — Generate a default app from a template (recommended if you're new)

1. Choose **"Generate a default app from a template"**
2. Optionally enter an app name; leave it blank and one is generated for you
3. **Template**: choose `web — website` (the only one for now; more are coming)
4. Click **Create**

The platform then does the rest asynchronously: creates the repository, initialises the docs, provisions a database (per environment), and generates a default deployment configuration. Once the status flips from `Creating` to `Success` you're good to go.

### Route B — Configure the app by hand

1. Choose **"Configure the app manually"**
2. Walk the multi-step wizard: app name, code repository, cloud deployment, domain, build commands, secrets
3. Save, return to the app list, and wait for `Success`

This is the route for "I already have my own repository and want to plug it in".

## What the app main version actually is

The app main version is the **default branch of this app's code repository** — usually `main` or `dev`.

- Every chat and task branches off the app main version before it starts working
- When work is done it merges back (or into the task main version first, then the app main version)
- What's "live" is a commit from that default branch that was released — not necessarily the newest one

A way to remember it: **app main version = a branch**; **the live version = a commit on that branch that was released**.

## Changing an app's configuration

The "Actions" column at the end of each row on [Apps](#/apps) gives you:

- **Edit** — reopen the wizard to change deployment, default branch, domain and so on
- **Release** — open the *Release details* page: past releases, plus the trigger for a production release
- **Delete** — remove it permanently (irreversible; be careful)

## Releasing code to production

On the *Release details* page, **you never pick a commit**. Either route works:

1. **Release to production directly**
   - Select the app in the "App" filter at the top (required, otherwise the button stays hidden)
   - Click the purple **Release to production** button in the top right
   - Write a release note in the dialog (required, up to 512 characters) and click **Release**
   - The platform triggers a new production release from the current state of the default branch, and a new `Production` row appears in the table below
2. **Promote an existing test build**
   - Any row with `Test` + status `Success` + Task ID `0` + Chat ID `0` has a **Go live** button at the end (these rows are built automatically after a merge to the default branch)
   - Click **Go live**, confirm in the dialog, and that exact build is switched to production
   - Ideal for "I already verified this in test and want the same image live"

> Code on the default branch **only takes effect once it has been released**. "Merge into app main version" just puts the code on the default branch — until you release, visitors still get the previous release.

## Common questions

**Q: Does creating from a template give me a working test link right away?**
A: The template route triggers a test deployment automatically. Once the status reads `Success`, give it a moment and the `Test` button in the "Links" column will open.

**Q: Can the app main version be something other than the default branch?**
A: You can change "default branch" in the configuration, and every subsequent chat and task will follow the new one.

Read next: `03-tasks.md`