# Contributing

NotNessie is open source. This page covers building from a clone, the dev
workflow, and how to run the tests and linter. It is derived from the repository
tooling.

## Prerequisites

- **Node.js >= 20**
- **pnpm** (the repo pins a `packageManager` version; [Corepack](https://nodejs.org/api/corepack.html)
  will install the right pnpm for you)
- **Docker** with Docker Compose, for the Postgres + pgvector database

## Get the source

```bash
git clone https://github.com/GreXLin85/notnessie.git
cd notnessie
pnpm install
```

## Build

Build the publishable packages (`@notnessie/core`, `@notnessie/mcp`,
`@notnessie/cli`) with tsup:

```bash
pnpm build
```

After building, you can run the CLI straight from the workspace:

```bash
node packages/cli/dist/index.js --help
# or, via the workspace script:
pnpm notnessie --help
```

## Start the database

```bash
pnpm db:up      # docker compose up -d  (Postgres + pgvector on :5432)
pnpm db:down    # docker compose down
```

## Enable embeddings (optional)

Semantic search depends on Transformers.js, whose `onnxruntime-node` native
binary is **not built by default** under pnpm 10 — installs of build scripts are
deferred until approved:

```bash
pnpm approve-builds
```

Until then (or with `NOTNESSIE_EMBEDDINGS=0`, or offline) search runs
keyword-only and everything still works. See
[Architecture → Embeddings](architecture.md#embeddings-local-first).

## Dev workflow

Type-check every package:

```bash
pnpm typecheck
```

Run the dashboard (builds the CLI first, then launches the daemon + Next.js UI):

```bash
pnpm dev
```

Individual packages expose `pnpm --filter @notnessie/<pkg> dev` for a tsup watch
build.

## Tests

Tests run with **Vitest** and are **DB-free** — they cover redaction, confidence,
id/text/vector helpers, and context-pack rendering, so you can run them without
Postgres:

```bash
pnpm test          # run once
pnpm test:watch    # watch mode
```

## Lint and format

Linting and formatting use **Biome**:

```bash
pnpm lint          # biome check .
pnpm format        # biome format --write .
```

## Before opening a pull request

Make sure the standard checks pass:

```bash
pnpm build
pnpm typecheck
pnpm test
pnpm lint
```

## Where things live

See [Architecture](architecture.md) for the package map. In short: domain logic
and storage live in `packages/core`, the MCP server in `packages/mcp`, the CLI
and Claude Code integration templates in `packages/cli`, and the dashboard in
`packages/dashboard`. `examples/demo-repo` is the pre-wired demo loaded by
`notnessie seed`.

## Documentation

This site is built with **MkDocs** and the **Material** theme. The pages live in
`docs/`, the config is `mkdocs.yml` at the repo root, and the pinned toolchain is
`docs/requirements.txt`. To preview locally:

```bash
pip install -r docs/requirements.txt
mkdocs serve
```

Pushes to `main` that touch `docs/**`, `mkdocs.yml`, or the docs workflow are
built and deployed to GitHub Pages automatically by
`.github/workflows/docs.yml`.