# Skill: Setup nerve from scratch

## When to use

Setting up the nerve project for local development from a fresh clone.

## Prerequisites

- **Node.js** ≥ 18
- **pnpm** ≥ 9 (`npm install -g pnpm`)
- **Git** access to `git.shazhou.work`

## Steps

### 1. Clone

```bash
git clone https://git.shazhou.work/uncaged/nerve.git
cd nerve
```

### 2. Install dependencies

```bash
pnpm install
```

This installs all workspace packages and links internal dependencies (`core` → `daemon` → `cli`).

### 3. Build all packages

```bash
pnpm -r run build
```

Build order is handled automatically by pnpm workspace — `core` builds first, then `daemon`, then `cli`.

### 4. Run tests

```bash
pnpm -r run test
```

Or test individual packages:

```bash
pnpm --filter @uncaged/nerve-core test
pnpm --filter @uncaged/nerve-daemon test
pnpm --filter @uncaged/nerve-cli test
```

### 5. Try the CLI

```bash
# Link the CLI globally
cd packages/cli && npm link

# Initialize a workspace
mkdir ~/my-nerve-workspace && cd ~/my-nerve-workspace
nerve init

# Edit senses in nerve.yaml, then:
nerve start      # start the daemon
nerve sense list  # list registered senses
nerve stop       # stop the daemon
```

### 6. Lint & format

```bash
pnpm run check    # biome lint check
pnpm run format   # biome auto-format
```

## Project structure

```
nerve/
├── packages/
│   ├── core/       # @uncaged/nerve-core — shared types, log store, blob store
│   ├── daemon/     # @uncaged/nerve-daemon — kernel, sense runtime, workflow manager
│   └── cli/        # @uncaged/nerve-cli — CLI commands (init, start, stop, sense, etc.)
├── docs/           # RFCs, conventions, skills
├── pnpm-workspace.yaml
└── biome.json      # linter/formatter config
```

## Key conventions

- **Monorepo** with pnpm workspaces
- **ESM only** — all packages output ESM (`"type": "module"`)
- **tsup** for builds, **vitest** for tests, **biome** for lint/format
- **SQLite** (better-sqlite3) for log store and blob store
- See `docs/coding-conventions.md` for code style rules

## Pitfalls

- **Must build before test** — daemon and cli import compiled output from core
- **better-sqlite3** requires native compilation — if `pnpm install` fails, ensure you have build tools (`build-essential` on Linux, Xcode CLI tools on macOS)
- **Node 18+** required — uses native `fetch`, `crypto.randomUUID`, etc.
- **pnpm only** — don't use npm/yarn, workspace links won't resolve correctly