# Coding-rulebook + pre-PR-review — new-machine setup

This is the operator's manual for replicating the whole system on another laptop.
Point Claude at `https://coderuleset.com/api/setup` and say "set this up on this machine"
and it can follow these steps. A visual overview PDF ships in the repo at
`claude-setup/coding-workflow.pdf`.

## What the system is
- A private rulebook (Postgres, served read-only at `https://coderuleset.com/api/rules/essentials`).
- A local pre-PR gate: embeds your diff and retrieves only the rules relevant to it
  (`/pre-pr-review`), nothing leaves the machine.
- Auto-mining of PR review comments into the rulebook.
The rulebook DB is shared across machines (it's remote); each laptop just needs the
tooling + local retrieval artifacts.

## Prerequisites (install first if missing)
- Node ≥ 20, **pnpm**, **git**, **GitHub CLI (`gh`)** — and `gh auth login` done.
- The Claude desktop app (or Claude Code CLI).

## Fast path
```bash
# 1. clone the tooling repo (private, on your own GitHub account)
git clone https://github.com/FrankoSolomun/pro-code.git ~/Code/pro-code
cd ~/Code/pro-code

# 2. add secrets — copy values from your password manager or another laptop's .env
cp claude-setup/.env.example .env
#    then edit .env and fill in DATABASE_URL (required) and GOOGLE_GEMINI_API_KEY (optional)

# 3. run the setup script (idempotent — installs deps, ~/.claude config, builds embeddings)
bash scripts/setup-claude.sh
```
That's it. The script installs dependencies, copies the loader + slash-commands into
`~/.claude/`, and generates the local embeddings + triggers. It prints what to do if a
prerequisite or secret is missing.

## What gets installed where
| Item | From | To |
|---|---|---|
| Rulebook fetch loader | `claude-setup/scripts/fetch_rulebook.sh` | `~/.claude/scripts/` |
| Slash-commands (`/pre-pr-review`, `mine-pr-rules`, …) | `claude-setup/commands/*.md` | `~/.claude/commands/` |
| Global rulebook instructions | `claude-setup/global-claude-md-snippet.md` | append to `~/.claude/CLAUDE.md` |
| Embeddings + triggers (local, ~20 MB) | generated by `scripts/embed-rules.mjs` + `derive-triggers.mjs` | `~/.claude/state/` |
| Retrieval / mining scripts | `scripts/` (come with the clone) | stay in the repo |

## Two things the script can't do for you
1. **Secrets.** `DATABASE_URL` and `GOOGLE_GEMINI_API_KEY` are never stored here. Put them in
   `~/Code/pro-code/.env` from your password manager. Without `DATABASE_URL`, nothing works.
2. **Your personal global rules.** Your own `~/.claude/CLAUDE.md` global preferences aren't
   published here — copy that file from a laptop you already use. The setup script appends only
   the rulebook-specific instructions and reminds you to bring the rest.

## Verify it works
```bash
bash ~/.claude/scripts/fetch_rulebook.sh          # should print a cached rules file path
# in any git repo with uncommitted changes:
git diff | node ~/Code/pro-code/scripts/retrieve-rules.mjs --k 40    # should print relevant rules
```
Then run `/pre-pr-review` in Claude inside a repo that has changes.

## Maintenance (important)
The local embeddings + triggers are snapshots of the rulebook. **After ANY rulebook change**
(a mining ingest, a curation edit), regenerate them on each machine you use, or new/changed
rules won't be retrievable:
```bash
cd ~/Code/pro-code && node scripts/embed-rules.mjs && node scripts/derive-triggers.mjs
```

## Scripts reference (`~/Code/pro-code/scripts/`)
- `setup-claude.sh` — this whole setup, idempotent.
- `embed-rules.mjs` — (re)build local rule embeddings (local model, no API).
- `derive-triggers.mjs` — (re)build file-glob / keyword / stack triggers per rule.
- `retrieve-rules.mjs` — given a diff, return the rules that matter for it (used by `/pre-pr-review`).
- `ingest-pr-feedback.mjs` — ingest synthesized rules (`--create-only`, `--dry-run`).
- `fetch-pr-comments.mjs` — pull all PR review comments for repos to a local corpus (mining).