# Setup And First Run

Use this page when someone has already installed ZoneGaze Matrix and needs the fastest path to a
working first session.

## Before First Launch

### Mac

- A Git project to manage.
- Either a supported CLI agent installed on `PATH`, or a configured native ZoneGaze Flow/Cline
  provider.

### Android

- The ZoneGaze Matrix APK installed.
- Time to let the owned Zone Terminal runtime finish its automatic setup.

### CLI

- Node.js 22 or newer.
- A Git repository to run inside.

## First Run: Fastest Path

### Mac

1. Open `ZoneGaze Matrix.app`.
2. If the runtime is offline, use the recovery screen or tray/menu actions to restart it.
3. Add or select a project.
4. Open `Settings` and confirm an agent/provider is ready.
5. Open `Plugin` and launch the workflow surface you want.

### Android

1. Open `ZoneGaze Matrix`.
2. Keep the app open while the runtime is prepared.
3. Watch **Dashboard** or **Runtime** until setup completes.
4. Save a launch folder.
5. Configure Git and SSH if you plan to commit or push.
6. Tap **Start**, then **Open**.

### CLI

1. Run `npx zonegaze-flow` from a Git repository.
2. Open the printed local URL if the browser does not open automatically.
3. Add or select a project in the board UI.

## Minimal Setup Checklist

1. Add a project.
2. Confirm an agent or provider is available.
3. Install or open the plugins needed for the workflow.
4. Create the first task, chat, note, or design session.
5. Review the result and save, commit, export, or hand off as needed.

## Which Plugins To Open First

| Goal | Recommended starting plugins | Routing doc |
| --- | --- | --- |
| Coding and review | Flow + Git + Code | [Use and workflows](use-and-workflows.md) |
| Project chat and reasoning | Chat + Flow | [Matrix plugin coordination](../plugins/plugin-coordination.md) |
| Dictation and quick capture | Whispr + Chat or Joplin | [Whispr plugin](../plugins/zonegaze-whispr.md) |
| Notes and durable context | Joplin + Research | [Joplin plugin](../plugins/zonegaze-joplin.md) |
| Design work | Open Design + Flow or Joplin | [Open Design plugin](../plugins/open-design.md) |
| Social workflow | Social Studio + Research + Whispr | [Social Studio plugin](../plugins/zonegaze-social-studio.md) |

## First Proof That Setup Worked

Setup is functionally complete when the user can do all of the following:

1. Open Matrix without cloning the repo or running contributor-only commands.
2. Add or select a project.
3. Launch at least one plugin surface successfully.
4. Start one real workflow such as a Flow task, Chat conversation, Joplin note, or design session.

## Next Reading

- [Getting started](../user/getting-started.md)
- [How-to guide](../user/how-to.md)
- [Use and workflows](use-and-workflows.md)
- [Plugin catalog](../plugins/README.md)
- [Contact and support](contact-and-support.md)
