# Developer Onboarding

## First Mental Model

The repository is a Matrix workspace. Matrix is the host product. Flow is one plugin inside that
host. The `flow/` directory name is historical and now contains shared foundations as well as Flow
plugin code.

## Repo Map

- `docs`: stable documentation and generated reference indexes.
- `plugins`: Matrix plugin packages and upstream source mirrors.
- `flow/common`: pure shared plugin-service helpers.
- `flow/contracts`: shared browser/runtime/platform/plugin contracts.
- `flow/runtime`: local runtime and host control plane.
- `flow/web`: shared React shell and plugin surfaces.
- `flow/product`: Flow-plugin-specific behavior layered outside shared foundations.
- `flow/kanban-core`: upstream-compatible kanban core.
- `platforms/desktop`: Electron Matrix host shell.
- `platforms/android`: Android Matrix host shell and owned Zone Terminal platform.
- `platforms/server-manager`: managed local service lifecycle helper.
- `test`: durable runtime and integration tests.

## Setup

```bash
npm install
npm --prefix flow/web install
npm --prefix platforms/desktop install
npm --prefix platforms/server-manager install
```

## Common Commands

```bash
npm run dev
npm run typecheck
npm run test:fast
npm run check:boundaries
npm run docs:build
```

If an npm script is blocked by the execution policy, run the underlying local command directly and
report the blocker.

## Development Rules

- Work from `development`.
- Use a task branch and isolated worktree for feature work.
- Keep direct Cline SDK imports behind `packages/cline-sdk`.
- Keep plugin/product behavior outside `flow/kanban-core`.
- Prefer typed contracts and SDK source types over local guesses.
- For frontend work, use Tailwind tokens and UI primitives from `flow/web/src/components/ui`.

## Documentation Rules

- Stable docs go under `docs/`.
- Generated docs go under `docs/reference/generated/`.
- Do not edit generated docs by hand.
- Run `npm run docs:build` after changing code or docs.
- Update [`docs/MASTER.md`](../MASTER.md) when adding stable docs.

## Next Reading

- [ZoneGaze Matrix overview](../product/zonegaze-matrix.md)
- [Codebase guide](../codebase/README.md)
- [Architecture index](../architecture/README.md)
- [Plugins](../plugins/README.md)
- [Documentation system](documentation-system.md)
