From 72ff04e390b4d43e7e24c9c095f2b2ea4db6e842 Mon Sep 17 00:00:00 2001
From: JC Brand <jc@opkode.com>
Date: Fri, 20 Mar 2026 12:28:04 +0200
Subject: [PATCH] docs: make CLAUDE.md agent-agnostic and add AGENTS.md symlink
 (#666)

Rename title/intro to be generic, add a 'Verifying changes' section,
coding conventions, and an auto-generated files table. Add AGENTS.md
as a symlink to CLAUDE.md so other agents pick up the same guide.
---
 AGENTS.md |  1 +
 CLAUDE.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 3 deletions(-)
 create mode 120000 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 00000000..681311eb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 640b4c94..49850cd9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
-# CLAUDE.md
+# Agent Guide
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding agents working with this repository.
 
 ## What is ThunderHub
 
@@ -18,11 +18,27 @@ npm run lint:check                               # ESLint without fix (used in C
 npm run test                                     # Jest (rootDir: src/, matches *.spec.ts)
 npm run test -- --testPathPattern="channels"     # Run tests matching a pattern
 npm run test:e2e                                 # E2E tests (config: test/jest-e2e.json)
-npm run generate                                 # GraphQL codegen (server must be running at localhost:3000)
+npm run generate                                 # GraphQL codegen — requires server running at localhost:3000; not for CI
 ```
 
 **Note:** Package manager is `npm`, not pnpm/yarn. Node version: see `.nvmrc`.
 
+## Verifying changes
+
+After making code changes, run these in order to confirm correctness:
+
+```bash
+npm run lint:check   # Check for lint errors (no auto-fix)
+npm run test         # Run unit tests
+npm run build        # Confirm the full build succeeds
+```
+
+Run a targeted test when touching a specific module:
+
+```bash
+npm run test -- --testPathPattern="<module-name>"
+```
+
 ## Architecture
 
 Monorepo with two apps under `src/`:
@@ -89,6 +105,7 @@ The `lightning` library returns errors as arrays `[title, string, { err }]`; `ln
 ## Pre-commit hooks
 
 Husky runs `lint-staged` on commit for `*.ts` and `*.tsx` files:
+
 1. `prettier --write`
 2. `jest --bail --findRelatedTests --passWithNoTests`
 3. `eslint --fix`
@@ -96,3 +113,29 @@ Husky runs `lint-staged` on commit for `*.ts` and `*.tsx` files:
 ## Prettier config
 
 Single quotes, trailing commas (es5), 2-space tabs, 80 char width, no parens on single arrow params. See `.prettierrc`.
+
+## Coding conventions
+
+### Server
+
+- Use `toWithError<T>(promise)` (from `utils/async.ts`) for LND calls that may fail — returns `[data, undefined] | [undefined, error]`. Use `to<T>(promise)` when you want to throw on error.
+- The `lightning` library errors are arrays; use the dedicated `to()` in `lnd.helpers.ts` (not the generic one) when wrapping raw `lnd` calls.
+- Tests are co-located as `*.spec.ts` next to the file under test.
+
+### Client
+
+- New UI components must use **shadcn/ui** (New York style). Do not add new styled-components.
+- Use the `@/` import alias for all client-side imports (maps to `src/client/src/`).
+- Follow the dual-context pattern (`useXState()` / `useXDispatch()`) for new shared state.
+- Icons: use **Lucide React** only.
+
+## Auto-generated files — do not edit
+
+The following files are generated automatically and must not be edited by hand:
+
+| File/pattern                                              | Generated by                                 |
+| --------------------------------------------------------- | -------------------------------------------- |
+| `schema.gql`                                              | NestJS GraphQL (code-first, on server start) |
+| `src/client/src/graphql/**/__generated__/*.generated.tsx` | `npm run generate` (GraphQL codegen)         |
+
+To regenerate: start the dev server (`npm run start:dev`) then run `npm run generate`.