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

# Recipes and gotchas

> High-leverage Neroli workflows, plus the things that usually trip people up.

These are the workflows that make Neroli feel different from scattered terminal
tabs. Start with the one that removes the most friction from your current repo.

## Isolated dev sessions

Use this when parallel agents need to run the app, database, or test stack at
the same time.

<Steps>
  <Step title="Prepare the session">
    Copy `.env.local` or generated config into the session without committing secrets.
  </Step>

  <Step title="Assign unique ports">
    Give each session its own frontend, backend, database, queue, or simulator ports.
  </Step>

  <Step title="Isolate services">
    Use a unique Docker project name, database name, schema, cache prefix, or local data directory for each session.
  </Step>

  <Step title="Expose Run and Stop">
    Pin Run in the toolbar and add Stop behavior so the session can clean up after itself.
  </Step>

  <Step title="Add Verify">
    Give humans and agents one command that proves the session is ready for review.
  </Step>
</Steps>

```txt theme={null}
Create Neroli automations for isolated dev sessions.

Prepare should copy env files safely, assign unique ports, and create isolated
Docker/database state. Run should start the app from this session. Stop should
tear it down. Verify should run the checks we use before review.
```

## Parallel feature work

Use this when you want several directions explored without mixing files.

1. Start one session per feature, fix, experiment, docs update, or review.
2. Give each session the context and outcome it needs.
3. Move planning work into Planning and active work into In Progress.
4. Let sessions run in parallel while Neroli tracks which ones need input.
5. Move substantial candidates to In Review and ask each agent to self-review.
6. Put validated candidates in Merge, then move them to Done or archive them.

<Tip>
  The point is not to make every task tiny. The point is to keep each stream of work inspectable.
</Tip>

## Group automation

Use this when a sidebar group keeps collecting the same manual work.

<Steps>
  <Step title="Pick the group">
    Choose the group where the work naturally gathers: In Review, Merge, Done, or another stage.
  </Step>

  <Step title="Create the action">
    Add a sidebar automation for that group. It can inspect the sessions in the group and act on the first or all of them.
  </Step>

  <Step title="Run from the header">
    Launch the automation from the group header instead of opening each session by hand.
  </Step>

  <Step title="Use moved triggers when useful">
    If entering a group should start follow-up work, use a Session moved automation for that destination.
  </Step>
</Steps>

```txt theme={null}
Create a Neroli automation for the In Review group.
It should inspect every session in that group, ask each agent to self-review,
summarize risks, and tell me which sessions need my attention.
```

## Browser verification

Use this when an agent changes a visible web flow.

<Steps>
  <Step title="Start the app from the session">
    Use the session's Run automation so the browser points at the right worktree.
  </Step>

  <Step title="Open the attached browser">
    Keep the page in a Neroli pane so the agent and human are looking at the same UI.
  </Step>

  <Step title="Ask the agent to verify">
    Have it inspect the page, click through the changed flow, check console or network evidence when useful, and report what it saw.
  </Step>

  <Step title="Review the evidence">
    Use the browser state, screenshots, logs, and diff together before merging.
  </Step>
</Steps>

```txt theme={null}
Verify the UI change in the attached Neroli browser.
Use the session's Run automation if needed, inspect the changed route, capture
what you saw, and tell me any console, network, or visual issues.
```

## Cloud handoff

Use this when a session should keep running away from your Mac, or when you want
more agents moving at once.

<Steps>
  <Step title="Start local">
    Get the session into a useful state locally first. The handoff snapshot includes conversation context, file edits, and workspace state.
  </Step>

  <Step title="Check setup">
    Make sure the workspace knows how to install, build, run, and verify itself without hidden local state.
  </Step>

  <Step title="Move to cloud">
    Send the session to cloud and keep watching status in Neroli.
  </Step>

  <Step title="Bring it back">
    Move the result local, run verification from the session, and review before merging.
  </Step>
</Steps>

<Warning>
  Cloud is not a place to hide messy setup. If setup, secrets, or network access are unclear locally, fix that before relying on handoff.
</Warning>

## Agent self-review

Use this before you read the diff yourself.

```txt theme={null}
Review your own work before I merge it.

Summarize what changed, inspect the diff for unrelated edits or risky files,
run the relevant checks from this session, fix anything obvious, and tell me
what still needs my attention.
```

Good self-review includes the changed behavior, verification result, known
risks, and any files you should inspect manually.

## Keep artifacts reviewable

Use this when agents generate docs, images, PDFs, spreadsheets, notebooks, or
other output files.

* keep source-code edits in Changes
* keep generated outputs visible as artifacts
* ask the agent which artifacts are final and which are scratch
* open important artifacts in a file viewer before merging
* ignore bulky build outputs unless they are intentional deliverables

## Gotchas

| Gotcha                                        | What to do                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| Ports collide across sessions                 | Assign ports in Prepare instead of hardcoding them.                                   |
| A command ran from the wrong repo             | Run it from the session pane or session automation.                                   |
| Verify passes outside Neroli but fails inside | Compare env, paths, generated files, and session setup.                               |
| Browser looks stale                           | Restart the session's Run action and reload the attached browser pane.                |
| Browser verification used the wrong app       | Start the app from the session's Run automation, then reload the attached browser.    |
| Cloud fails during handoff                    | Read the recovery message, then fix setup, auth, network access, or pending sync.     |
| Simulator or preview missing in cloud         | Keep that work local; those panes depend on your Mac.                                 |
| Generated files are noisy                     | Keep build outputs ignored unless they are real review artifacts.                     |
| Two sessions edit the same area               | Review them in sequence and merge deliberately.                                       |
| The board is crowded                          | Move validated work to Done, then archive sessions you no longer need.                |
| A group repeats the same manual work          | Add a sidebar automation for that group.                                              |
| Provider auth is missing                      | Sign in to the provider locally, then start a new session.                            |
| Secrets appear in a diff                      | Stop and remove them before review. Automations should copy secrets, not commit them. |

## When to add an automation

Add one when you repeat a task more than twice, when agents keep asking how to
run something, or when a setup mistake blocks parallel work.

Good automation names are clear and obvious: Prepare session, Run dev, Stop,
Build, Verify, Improve automations, Update docs.

Next: see the agent-facing details in [Agent details](/docs/reference).