# lema docs — Quickstart

lema-mcp is the local, database-less MCP server that serves a repo's decisions — the chosen approach, the constraints, the consequences, and the alternatives that were ruled out — to any coding agent that asks. Local, no account.

## Step 1 — Wire your repo

`npx lema-mcp init` writes a ready `.mcp.json`, an `AGENTS.md`, a guard hook, and a nudge hook into your repo. Or point lema straight at any repo with ADRs via `--repo`:

```
npx lema-mcp --repo github.com/your-org/your-repo
```

Leave `--adr-dir` off and it auto-discovers `docs/adr` and the like. Cold `init` wires the local checkout (no `--repo`):

```json
{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["-y", "lema-mcp@0.21.3"]
    }
  }
}
```

### Flags
- `--repo` — github.com/org/repo to fetch (public; GITHUB_TOKEN for private), or a label for local --adr-dir mode.
- `--adr-dir` — ADR directory (local path, or in-repo subpath with --repo). Empty auto-discovers docs/adr, docs/decisions, and the like.
- `--ref` — git ref or branch to fetch from (default: the repo's default branch); remote --repo only.
- `--pattern` — ADR filename regex (default matches NNNN-*.md / NNN_*.md); widen it for other conventions.
- `--openspec-dir` — OpenSpec root to read alongside ADRs (a local ./openspec directory is auto-detected).
- `--capture-file` — The local decision store propose / record_decision append to (default .lema/decisions.jsonl).

## Step 2 — Capture as you decide

As decisions get made, `propose` writes them — the chosen option and the rejected alternatives — into the graph, and `check_decided` surfaces what's already settled. The `guard` and `nudge` hooks installed by `init` wire this into your agent's loop.

## Step 3 — Ask the graph

Before writing code, an agent calls `search_decisions` and gets back tight, typed claims — each carrying its source — not whole documents. Example: "why did React move from classes to Hooks — and what was ruled out?"

- **chosen** (reactjs/rfcs#68): Hooks let function components hold state and lifecycle, so stateful logic can be reused without wrapper components.
- **rejected** (reactjs/rfcs#68): A mixins-style sharing mechanism was ruled out before Hooks — name collisions and implicit dependencies.
- **constraint** (rules of hooks): Hooks are called at the top level in the same order each render — never inside conditionals or loops.
- **consequence** (reactjs/rfcs#68): Classes stay supported; Hooks were additive and opt-in, not a migration mandate.

The rejected claim — the why-not — is the part no other tool surfaces: the agent learns what was already argued and ruled out, so it doesn't reopen it.