> ## 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.

# Agent details

> The small amount of technical detail agents and advanced users need.

Most users should live in the Mac app. This page is for agents, repo owners, and
advanced debugging.

## What Neroli gives each session

| Thing    | Why it exists                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------------- |
| Worktree | Keeps files and branch state separate from other sessions.                                           |
| Panes    | Keeps terminals, browser, simulator, previews, diffs, files, and review evidence with the task.      |
| Actions  | Runs setup, run, build, verify, and cleanup from the right session.                                  |
| Status   | Shows whether work is planning, running, in review, merging, done, local, cloud, or needs attention. |

## Agent CLI bridge

The `neroli` CLI is mainly for agents and automations. It lets them inspect the
current session instead of guessing paths, panes, browsers, simulators, or
automation names.

```sh theme={null}
neroli identify --json
neroli state list --json
neroli browser look
neroli ios-simulator status
```

Common groups:

| Command                 | Use                                                        |
| ----------------------- | ---------------------------------------------------------- |
| `neroli identify`       | Find the current workspace, session, and pane context.     |
| `neroli state`          | Start, stop, restart, or inspect known workspace activity. |
| `neroli browser`        | Inspect or drive the browser pane attached to the session. |
| `neroli ios-simulator`  | Use the simulator owned by this workspace.                 |
| `neroli automations`    | Inspect or manage saved automations.                       |
| `neroli automation-run` | Report outcomes from an automation run.                    |

This is why agents can create automations, inspect recent sessions, use attached
browsers, and keep work tied to the right workspace.

## Useful agent requests

Ask agents to use Neroli when the answer depends on workspace context:

```txt theme={null}
Use the attached Neroli browser to verify this UI flow.
```

```txt theme={null}
Inspect recent Neroli sessions and suggest automations that would make this repo easier to work in.
```

```txt theme={null}
Create a Run, Stop, and Verify automation for this workspace.
```

```txt theme={null}
Update the docs from the feature you just shipped, then open the generated page or artifact for review.
```

Those requests work because the agent can discover the current session, panes,
services, automations, and run history through Neroli instead of guessing from
the shell alone.

## Safety rules

* A worktree is isolation for review, not a security sandbox.
* Commands can access what your macOS user can access.
* Do not commit `.env`, certificates, API keys, generated credentials, or local-only config.
* Use cloud only for work whose setup, secrets, and network access are intentional.
* If a command behaves strangely, first check that it ran from the right session path.

## Quick troubleshooting

| Problem                     | First check                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------- |
| Provider missing            | Sign in to the provider from your normal terminal, then start a new session.       |
| App opens the wrong state   | Start the app from the session Run action, not a random terminal.                  |
| Verify fails only in Neroli | Run the same command from `NEROLI_WORKTREE_PATH` and check missing local setup.    |
| Cloud fails                 | Read the visible recovery message, then fix setup, auth, network, or pending sync. |
| Browser looks stale         | Restart the session's Run action and reload the attached browser pane.             |