# Core concepts

Five minutes from now you'll be able to answer:

- What is an **app**, and why is every app bound to an agent?
- What do **app main version** and **task main version** mean, and why two layers?
- Why are **chats** and **tasks** separate? When do you use which?
- Who are **todos**, **OKRs** and **secrets** for?

## App

**An app is a project you want the AI to work on with you.**

Every app holds two things:

1. **A code repository** — where the AI actually changes code (a Git repository / working directory)
2. **A resident agent** — the executor, running in the cloud or locally, that receives work, clones the code, applies changes and pushes results

The app list lives on the [Apps](#/apps) page. Each row shows:

- **Status** — how initialisation and updates went, e.g. `Creating` / `Creation failed` / `Updating` / `Success`
- **Links** — quick jumps to the test and production environments

## App main version

The app main version is the **default branch of the app's code repository** — usually `main` or `dev`. It is the **source of production releases**, but it is **not necessarily the newest commit**:

- Every chat and task branches off the app main version before it starts working
- When the work is done, "merge into app main version" folds the change back into that default branch
- What's actually live is **a commit on that branch that has been released** — it may lag behind the newest commit, because the newest one may never have been released
- So "app main version" is a *branch*-level concept, not a specific commit

If it helps: think of the app main version as `main` on GitHub. Each "release to production" pushes the current state of that branch (or an earlier successful test build) live — **you never have to pick a commit yourself**. `02-apps.md` covers the release flow.

## Task main version

The task main version is a **long-lived branch that belongs to one task**. It only exists inside tasks.

- A single task can contain **many chats**
- Each chat's changes merge into the **task main version** first; the whole thing merges into the app main version once the task is finished
- Ideal for "one big piece of work, delivered over several sittings"

By analogy:

| Concept | Git equivalent |
|---------|----------------|
| App main version | the `main` branch (production ships a commit from it) |
| Task main version | a long-lived `feature/xxx` branch |
| A single chat's branch | a throwaway `chat/xxx` branch |

## Chats and tasks

Think of it this way: **a chat is a one-on-one conversation** — the AI works on one thing at a time. **A task is a group chat** — several chats push the same larger piece of work forward **in parallel**, and it all merges once the work is complete.

|            | Chat | Task |
|------------|------|------|
| Purpose    | lightweight, spur-of-the-moment | larger work, developed in parallel |
| Concurrency | chats **queue** behind one another | chats inside a task run **in parallel** |
| Status     | Waiting / Running / Done / Stopped | Not started / In progress / Suspended / Finished |
| Contains   | a thread of messages | a title + several chats + a change history |
| Merges     | straight into the app main version | into the task main version first, then the app main version |
| Good for   | "fix this bit of copy" | "refactor a module" |

See `04-chats.md` for the full comparison.

## Everything else

- **[Todos](#/todos)** — small items broken out while a chat or task runs, appended like sticky notes so nothing gets lost. You can add your own too.
- **[OKRs](#/okr)** — the goals you set for yourself. The AI takes them into account so it can prioritise work that actually moves your goals.
- **[Secrets](#/secrets)** — your API token. An agent, local or in the cloud, needs it configured before it can call the Quodara API.
- **[Store](#/store)** — buy credits, subscribe to advanced models, unlock capabilities.
- **[Support](#/user-feedback)** — the channels (links / QR codes) for reaching a human.

## One diagram

```
                ┌──────────────────┐
   you ────────►│  Chat (lightweight)│──► merge ──► app main version (default branch)
                └──────────────────┘
                ┌──────────────────────────────────┐
   you ────────►│  Task                             │
                │  ├─ Chat ─► merge ─► task main    │──► merge ──► app main version
                │  └─ Chat ─► merge ─► task main    │
                └──────────────────────────────────┘
                                                  │
                                                  └─► click "Release" on the app list:
                                                      · release to production directly, or
                                                      · promote a successful test build
```

Read next: `02-apps.md`