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

# Getting started

# Getting started

How to install `rekkal`, configure its environment variables, and run it locally.

## Prerequisites

* **Node.js** 20 or newer.
* **pnpm** — the package manager for this repo. Install with `npm install -g pnpm` or see [pnpm.io/installation](https://pnpm.io/installation).

## Install

```bash theme={null}
git clone https://github.com/maximebrmd/rekkal.git && cd rekkal
pnpm install
```

The Claude Code skills under `.claude/skills/` are committed to the repo, so they already arrive with `git clone` — no separate skills step is required (see [agent-skills.md](./agent-skills.md)).

## Environment variables

Copy the example file and fill in real values:

```bash theme={null}
cp .env.example .env.local
```

Every variable the app reads is listed in [`.env.example`](../.env.example) with a placeholder value — treat that file as the authoritative list. It covers Supabase (`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SERVICE_ROLE_KEY`), Stripe (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `NEXT_PUBLIC_STRIPE_PRICE_PRO`, plus `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — optional, reserved for client-side Stripe.js), Resend (`RESEND_API_KEY`, `RESEND_FROM`), the answer engines (`PERPLEXITY_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`), the cron routes' `CRON_SECRET`, the rate limiter's `RATE_LIMIT_ADDRESS_SECRET`, the two host origins (`NEXT_PUBLIC_APP_URL` and the optional `NEXT_PUBLIC_MARKETING_URL` — see [hosts.md](./hosts.md); both default to `http://localhost:3000`, so local development needs neither), and the local-only `REKKAL_ONBOARDING_FIXTURE` and `REKKAL_DASHBOARD_FIXTURE`.

The engine keys are rekkal's own, never a customer's, and none of them is required locally: an engine with no key is skipped rather than failing the run, and `pnpm test` is green with an empty environment because the fixture adapter replays recorded payloads through the real parsers. See [analytics-pipeline.md](./analytics-pipeline.md).

`RATE_LIMIT_ADDRESS_SECRET` is required to click through onboarding at all, fixture or not: the rate limit buckets on the calling address and stores a keyed hash of it rather than the address, so without the key it refuses ("We could not check your usage. Try again in a moment.") instead of falling back to plaintext or to one shared bucket. Any string works locally; `pnpm test` supplies its own, which is why the suite stays green with an empty environment. Rotating it resets every in-flight address window. See [onboarding.md](./onboarding.md).

Onboarding generation calls `OPENAI_API_KEY`. To click through it locally without one, set `REKKAL_ONBOARDING_FIXTURE=1` — it replays a bundled payload through the production parser, and is ignored when `NODE_ENV=production`, so it never belongs in a deployed environment. See [onboarding.md](./onboarding.md). The signed-in dashboard has the same kind of switch for a machine with no seeded rollup rows, `REKKAL_DASHBOARD_FIXTURE=1`, under the same production guard — see [dashboard.md](./dashboard.md).

`.env*` files are gitignored — never commit real secrets. When you introduce a new variable, add its name and a placeholder to `.env.example` in the same change.

## Database schema

The schema lives as versioned SQL in [`supabase/migrations/`](../supabase/migrations) — the auth/billing foundation plus the analytics tables, all under Row Level Security. Apply it to your Supabase project with the Supabase CLI (`supabase db push`, or `supabase migration up` locally). See [supabase.md](./supabase.md) for what the schema contains and how types are kept in sync.

## Run locally

```bash theme={null}
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000). The dev server hot-reloads on file changes.

## Scripts

| Command          | What it does                                                                                                                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm dev`       | Start the Next.js dev server on port 3000.                                                                                                                                                                  |
| `pnpm build`     | Produce a production build.                                                                                                                                                                                 |
| `pnpm start`     | Serve the production build (run `pnpm build` first).                                                                                                                                                        |
| `pnpm lint`      | Run ESLint.                                                                                                                                                                                                 |
| `pnpm test`      | Run the Vitest test suite once (colocated `*.test.ts`).                                                                                                                                                     |
| `pnpm docs:llms` | Regenerate every derived doc from README.md and the docs listed in `llms.txt`: `llms-full.txt`, plus the product-overview blocks in `llms.txt` and `AGENTS.md`. Run it after editing the README or any doc. |

## Next steps

* Read [stack.md](./stack.md) for what each layer does and why it was chosen.
* Read [CLAUDE.md](../CLAUDE.md) for the project structure and conventions.
* Wire up a specific layer: [supabase.md](./supabase.md), [stripe.md](./stripe.md), [email.md](./email.md), [ui.md](./ui.md).