# Developer Setup

This page is the short path for contributors who already have the repository
checked out and want a working local SF development environment.

## Prerequisites

- Node.js 26.1 or newer
- npm
- Git
- Rust toolchain for native engine work
- GitHub CLI for label, issue, and PR workflows
- Docker or a compatible container runtime for devcontainer verification

## First-Time Setup

```bash
npm install
npm run secret-scan:install-hook
node scripts/tech-debt-scan.mjs
```

Optional but recommended:

```bash
devcontainer build --workspace-folder .
```

## Daily Checks

Use the narrowest command that proves the change:

```bash
npm run lint
npm run typecheck:extensions
npm run test:unit
```

Before shipping changes that affect the CLI runtime:

```bash
npm run build:core
npm run test:smoke
```

For coverage-sensitive changes:

```bash
npm run test:coverage
```

The global floor is intentionally modest, but autonomous paths have stricter
coverage thresholds in `vitest.config.ts`.

## Environment Variables

SF-specific environment variables are parsed through `src/env.ts` for typed
callers. Add new `SF_*` variables there before introducing new production reads.
Document user-facing variables in `docs/user-docs/configuration.md`.

Common local overrides:

| Variable | Purpose |
|----------|---------|
| `SF_HOME` | Redirect global SF runtime state away from `~/.sf`. |
| `SF_AGENT_DIR` | Override the managed agent directory used by headless/runtime loaders. |
| `SF_PROJECT_ID` | Override the project state key; must be alphanumeric, hyphen, or underscore. |
| `SF_BIN_PATH` | Point child processes at a specific SF loader. |

## Contribution Contract

Every behavioral change starts with a failing behavior test or executable
evidence. Keep commits focused, avoid drive-by formatting, and do not commit
transient `.sf/` runtime state.