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

# Development

> From a clean clone to a green pnpm verify, and the commands you use every day.

## Set up from a clean clone

You install one thing system-wide, [mise](https://mise.jdx.dev). It provisions the rest from `mise.toml`.

**1. Install mise**

```bash theme={"system"}
curl https://mise.run | sh
```

**2. Provision the toolchain**

```bash theme={"system"}
mise install
```

This reads `mise.toml` and installs the pinned tools.

| Tool | Used for |
| - | - |
| `node` 24 | TypeScript toolchain, Turborepo |
| `pnpm` 12 | Workspace manager. The version must equal `packageManager` in `package.json` |
| `gitleaks` | Secret scanning in the pre-commit hook and `pnpm secrets:scan` |
| `infisical` | The vault CLI behind `pnpm linear`, `pnpm pr:merge` and the MCP wrapper |
| `uv` | Python tool runner, pinned in `mise.toml` |
| `maestro` | Mobile end-to-end flows (needs a JDK on `PATH`) |

**3. Install dependencies**

```bash theme={"system"}
pnpm install
```

This resolves every member against the catalogs in `pnpm-workspace.yaml` and installs the git hooks through the `prepare` script (`lefthook install`). If hooks do not run after install, check that pnpm was allowed to run lefthook's install script in `pnpm-workspace.yaml`.

**4. Verify the setup**

```bash theme={"system"}
pnpm verify
```

This is the full gate. If it is green locally, CI should be green ([CI](/runbooks/ci)).

### Mobile

The mobile app needs more only when you run it on a device or simulator: Xcode with an iOS simulator for iOS, Android Studio for Android. `pnpm mobile` starts Expo (Metro on port 8081). Release builds are EAS's job, not your laptop's ([Mobile release](/runbooks/mobile-release)).

### Secrets

Day-to-day development needs no secret. The only tokens are for MCP servers (`.mcp.json`), and they come from the Infisical vault at `/agents` through `tools/scripts/mcp.sh`. There is no `.env` file. See [Secrets](/runbooks/secrets).

### Encore

Services are plain TypeScript workspace members under `services/<name>` with no Encore files. Encore is the generated runtime target: `stackra gen` will emit the Encore app into the gitignored `.stackra/encore/` ([0091](/adr/0091-generated-encore-app-in-stackra-folder), [0124](/adr/0124-encore-is-the-generated-runtime-target)). The generator is not built yet, so there is no Encore app to run today.

## Daily commands

| Command | What it does |
| - | - |
| `pnpm dev` | Every member's dev server (Turborepo TUI) |
| `pnpm console` / `pnpm docs` / `pnpm mobile` | One app's dev server |
| `pnpm check` | Format check, lint and typecheck |
| `pnpm test` | Every member's vitest suite |
| `pnpm verify` | The full gate: format, lint, typecheck, test, build, `validate`, `boundaries`, `knip` |
| `pnpm verify:affected` | The turbo part of the gate, only for members changed since `main` |
| `pnpm validate` | Repository shape: catalogs only, tier tags, tsconfig presets, forbidden dependencies, required files |
| `pnpm new <kind> <name>` | Scaffold a member ([Scaffolding](/guides/scaffolding)) |
| `pnpm changeset` | Record a release note for the members you changed |
| `pnpm secrets:scan` | gitleaks over the whole history |

> [!TIP]
>
> Run one member's task with a filter: `pnpm turbo run test --filter=@figentra/console`. Or `cd`
> into the member and call its script directly when you do not want Turborepo's ordering.

## Troubleshooting

* **`pnpm install` fails on the pnpm version.** `mise.toml` and `packageManager` must agree; run `mise install` and retry.
* **Git hooks never run.** Run `pnpm install` again, or `pnpm exec lefthook install`. The hooks only check; they never rewrite files.
* **A step works locally and fails in CI.** Compare the tool version in `mise.toml` with what CI installs, and check the step did not rely on a file git ignores.
* **gitleaks is not installed.** The pre-commit hook skips it with a notice and CI still scans; run `mise install` to get it.

See also [Definition of done](/guides/definition-of-done) and [Commits and releases](/guides/workflow).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.