docs: refresh claude contributor notes (#118)

Author: robbeverhelst

CLAUDE.md

@@ -1,33 +1,49 @@
-# Tsarr - TypeScript SDK for Servarr APIs
+# Tsarr Contributor Notes
 
-## Project Overview
-Type-safe TypeScript SDK for Servarr APIs (Radarr, Sonarr, etc.) generated from Swagger/OpenAPI specs. Optimized for Bun runtime and Infrastructure-as-Code workflows.
+## What This Repo Is
+- Tsarr is a TypeScript SDK and CLI for the Servarr ecosystem: Radarr, Sonarr, Lidarr, Readarr, Prowlarr, and Bazarr.
+- The published package targets Node.js (`>=18.20.8`), while Bun is used for local development, build, generation, and tests.
+- This repo already ships generated clients, handwritten wrappers, a CLI, packaging assets, and user-facing docs. Do not treat core features as "future work".
 
-## Key Commands
-- `bun install` - Install dependencies
-- `bun run dev` - Run development server
-- `bun run build` - Build the project
-- `bun run lint` - Check code quality
-- `bun run lint:fix` - Fix linting issues
-- `bun run format` - Format code
-- `bun run typecheck` - Type check without emitting
+## Read First
+- `README.md` for product overview, install paths, and developer commands.
+- `docs/cli.md` for CLI behavior and supported command patterns.
+- `docs/usage.md` for SDK usage examples.
+- `docs/distribution.md` and `packaging/` for release and packaging workflows.
 
-## Architecture
-- **Runtime**: Bun (leverages native fetch API)
-- **Structure**: Modular design (separate modules per Servarr app)
-- **Generation**: Uses swagger-typescript-api for type-safe clients
-- **Target**: Tree-shakable, lightweight SDK for IaC environments
+## Core Commands
+- `bun install` - install dependencies
+- `bun test` - run tests
+- `bun run build` - regenerate clients/types and build the package
+- `bun run generate` - regenerate all OpenAPI-derived clients
+- `bun run refresh:specs` - refresh local OpenAPI specs
+- `bun run typecheck` - run TypeScript checks
+- `bun run lint` - run Biome checks
+- `bun run cli -- --help` - inspect the CLI locally
 
-## Development Notes
-- Source code in `src/` directory
-- Generated APIs live in `src/generated/<service>/`, with hand-written wrappers in `src/clients/<service>.ts`
-- Uses Biome for linting/formatting instead of ESLint/Prettier
-- Use conventional prefixes for commit messages and PR titles: `feat:`, `fix:`, or `chore:`
-- CI pipeline runs on all pushes and PRs
-- Renovate handles dependency updates weekly
+## Repo Map
+- `src/cli/` - CLI entrypoint, shared command framework, output formatting, config, prompts
+- `src/clients/` - handwritten service wrappers exposed as public SDK entrypoints
+- `src/generated/` - generated OpenAPI clients and types for each service
+- `src/core/` - shared config validation, error types, and HTTP helpers
+- `scripts/` - code generation, spec refresh, type export, and packaging automation
+- `specs/` - local OpenAPI inputs used by generation
+- `tests/` - unit, CLI, and integration coverage
+- `examples/` - runnable SDK examples
 
-## Future Implementation
-- Swagger file collection from Servarr instances
-- Code generation scripts using `swagger-typescript-api`
-- Modular API clients for each Servarr app
-- Integration with PrepArr/CodeArr sidecar project
+## Generation Rules
+- Generated code lives under `src/generated/`. Prefer changing generator inputs or scripts over editing generated files by hand.
+- Client generation uses `@hey-api/openapi-ts`, not `swagger-typescript-api`.
+- `scripts/generate.ts` includes Bazarr-specific spec normalization. Preserve that behavior when touching generation.
+- If you change API surface area, keep generated code, handwritten wrappers, exports, and docs aligned.
+
+## Editing Guidance
+- Most product logic changes belong in `src/cli/`, `src/clients/`, `src/core/`, or `scripts/`.
+- Keep CLI docs and smoke tests in sync when you add or rename commands.
+- Treat `README.md` and `docs/` as user-facing sources of truth. Keep this file short and operational.
+- There is no development server in this repo. The `dev` script runs the library entrypoint and is not an app server workflow.
+
+## Quality Bar
+- Use Biome for formatting and linting.
+- Prefer adding or updating tests when changing command definitions, output behavior, config handling, or client wrappers.
+- Preserve modular exports for per-service imports such as `tsarr/radarr` and `tsarr/radarr/types`.