> ## Documentation Index
> Fetch the complete documentation index at: https://neroli.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> The mental model behind Neroli workspaces, sessions, panes, automations, and cloud.

Neroli feels simple when you treat **the session** as the unit of work.

A session is not just a terminal tab. It is an isolated worktree, provider TUI,
panes, status, automations, review state, and optional cloud handoff moving
together.

<Frame caption="A session keeps the agent, files, panes, automations, status, and review evidence together.">
  <div className="not-prose rounded-xl border border-dashed border-gray-300 bg-gray-50 p-8 text-center text-sm text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300">
    Placeholder image: one Neroli session containing a provider TUI, browser pane, run automation, changed files, and review status.
  </div>
</Frame>

## Workspace, session, worktree

| Term      | What it means                                                      |
| --------- | ------------------------------------------------------------------ |
| Workspace | A repository opened in Neroli.                                     |
| Session   | One agent run with its own branch, panes, status, and automations. |
| Worktree  | The Git isolation boundary that keeps a session's files separate.  |
| Provider  | The coding agent you choose for the session.                       |

This is what lets you run multiple agents without losing track of which files,
commands, browser, or review belong to which job.

## What belongs to a session

| Session piece         | Why it matters                                                                   |
| --------------------- | -------------------------------------------------------------------------------- |
| Provider conversation | The agent chat stays tied to the work it produced.                               |
| Worktree and branch   | Files stay isolated until you choose what lands.                                 |
| Panes                 | The browser, simulator, terminals, diffs, and file viewers stay with the task.   |
| Automations           | Run, Build, Verify, Stop, and setup happen from the right workspace.             |
| Artifacts             | Generated images, PDFs, markdown, notebooks, and spreadsheets stay reviewable.   |
| Status                | Waiting, failed, blocked, cloud, ready, and review states are visible.           |
| Board group           | Planning, In Progress, In Review, Merge, and Done keep many sessions manageable. |

## Why direct TUIs matter

Neroli launches the real provider interfaces directly. That keeps the app fast
and avoids a stale wrapper around your agents.

You still get the provider's native behavior, shortcuts, auth, model features,
and release-day updates. Neroli adds the workspace layer around it: isolation,
visibility, automations, panes, review, and cloud handoff.

## Session panes

Panes keep useful context attached to the work instead of scattered across your
desktop.

| Pane         | Use it for                                                                    |
| ------------ | ----------------------------------------------------------------------------- |
| Provider TUI | Talk to the provider you chose for the session.                               |
| Terminal     | Run commands inside the session worktree.                                     |
| Browser      | Inspect the app, test flows, capture evidence, and let agents verify UI work. |
| Simulator    | Work with the session's dedicated iOS simulator.                              |
| Preview      | Inspect generated previews and local app surfaces.                            |
| Diff viewer  | Review changed files from the session.                                        |
| File viewer  | Open generated artifacts, markdown, images, PDFs, and text outputs.           |

<Info>
  Cloud sessions can keep terminal, browser, diff, and file panes. Simulator and preview panes are local-only because they depend on your Mac.
</Info>

## Status is part of the product

Neroli tracks whether a session is running, waiting for input, asking for
approval, blocked, failed, ready for review, local, or cloud. The point is not
to watch every token. The point is to know which session needs attention.

## Agents can use the workspace too

The Neroli CLI is mostly for agents and automations. It lets them inspect the
current workspace, attached panes, browser, simulator, known services, recent
sessions, and saved automations. That is why you can ask an agent to run the
browser, verify a UI flow, create setup automations, or analyze recent sessions
without handing it a pile of local paths.

## The useful habit

When you start a job, think in this order:

<Steps>
  <Step title="Pick the session">
    Start fresh for new work, or continue an existing session when the context already lives there.
  </Step>

  <Step title="Attach the right panes">
    Add the browser, terminal, simulator, diff, or file viewer that makes the work visible.
  </Step>

  <Step title="Use automations">
    Run the workspace's setup, run, build, verify, and stop actions from the session.
  </Step>

  <Step title="Move the session">
    Use the sidebar board to reflect where the work actually stands.
  </Step>

  <Step title="Review before merging">
    Ask the agent to self-review, inspect the result, then decide what lands.
  </Step>
</Steps>

Next: organize parallel work with the [Session board](/docs/sessions), then turn the
model into repeatable workflows with [Automations](/docs/automations).