docs: enhance repository guidelines and documentation structure

Author: Thavarshan

AGENTS.md

@@ -1,12 +1,14 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
+
 - **src/** – Strict TypeScript sources: `state.ts` (Zod schemas), `graph/auralyze-graph.ts` (LangGraph), `tools/` (client contracts), `config/llm.ts`, `prompts/`, and `dev.ts`.
 - **test/** – Vitest suites mirroring feature areas (`state`, `tools`, `config`, `graph/unit`, `graph/integration`) plus coverage helpers.
 - **docs/** – VitePress site (`docs/.vitepress/config.ts`) with guides for onboarding, architecture, testing, and releases.
 - **dist/** – tsup output (ESM/CJS bundles + `.d.ts`). Regenerated via `npm run build` or the `prepare` script.
 
 ## Build, Test, and Development Commands
+
 - `npm run lint` – ESLint (strict TS config, Prettier formatting on demand via `npm run format`).
 - `npm run typecheck` – `tsc --noEmit` to verify contracts without emitting JS.
 - `npm test -- --run` / `--coverage` – Vitest suites with optional coverage (target 100% over `src/`).
@@ -15,27 +17,32 @@
 - `npm run docs:dev` / `docs:build` – VitePress documentation preview/build.
 
 ## Coding Style & Naming Conventions
+
 - TypeScript, strict + `noImplicitAny`. Use `import type` for type-only dependencies.
 - ESM modules with explicit `.ts` specifiers; kebab-case filenames (`audio-metadata-tool.ts`).
 - Formatting: Prettier (2-space indent, single quotes). Linting: ESLint (`npm run lint`).
 
 ## Testing Guidelines
+
 - Framework: Vitest with globals enabled. Stub injected clients using `vi.fn()` for deterministic runs.
 - Suites live alongside the feature under test; file names follow `area/file.kind.test.ts`.
 - Coverage: run `npm run test -- --coverage --run`; CI expects full coverage across `src/`.
 
 ## Architecture Overview
+
 - `runAuralyzeSession(input, deps)` builds a LangGraph pipeline (`validateInput → metadataStep → analysisStep → feedbackStep → finalize`).
 - Dependencies are injected clients (`audioMetadataClient`, `audioAnalysisClient`, `feedbackClient`); the engine never touches ffmpeg or HTTP endpoints directly.
 - `OpenAIFeedbackClient` (in `src/config/llm.ts`) wraps the OpenAI SDK; other LLM providers can implement the `FeedbackClient` interface.
 
 ## Commit & Pull Request Guidelines
+
 - Use descriptive commits (e.g., `graph: add crest-factor reducer`). Squash only when keeping history readable.
 - Run `npm run ci` locally before opening a PR; CI mirrors the same commands.
 - PRs should link the tracking ticket, summarize behavior changes, and include test results or coverage output. Attach screenshots/logs if the change impacts tooling or docs.
 - Never commit secrets. Configure credentials via env vars or GitHub secrets (`DOCS_PUBLISH_TOKEN`, `GITHUB_TOKEN`, etc.).
 
 ## Security & Configuration Tips
+
 - Install from GitHub Packages by mapping `@auralyze:registry=https://npm.pkg.github.com` and authenticating with `${GITHUB_TOKEN}`.
 - The docs workflow (`.github/workflows/docs.yml`) pushes to a separate repo/branch; configure `DOCS_PUBLISH_TOKEN`, and optionally `DOCS_REPOSITORY` / `DOCS_BRANCH`.
 - `src/dev.ts` is a playground only—do not ship it in production; rely on the published bundle from `dist/`.

CLAUDE.md

@@ -7,6 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 This repository contains the Auralyze Engine, a LangGraph-powered workflow engine for AI-driven audio mix analysis. The actual project code lives in the `engine/` subdirectory.
 
 **Key directories (all under `engine/`):**
+
 - `src/` - TypeScript source code with strict typing
   - `state.ts` - Zod schemas for engine state and analysis data
   - `graph/auralyze-graph.ts` - LangGraph workflow orchestration
@@ -23,6 +24,7 @@ This repository contains the Auralyze Engine, a LangGraph-powered workflow engin
 **All commands must be run from the `engine/` directory.**
 
 ### Essential Commands
+
 ```bash
 cd engine
 npm install              # Install dependencies
@@ -31,6 +33,7 @@ npm run dev             # Run ts-node playground (src/dev.ts) with mock clients
 ```
 
 ### Individual Tasks
+
 ```bash
 npm run lint            # ESLint over src/**/*.ts
 npm run typecheck       # TypeScript contract verification (tsc --noEmit)
@@ -41,13 +44,15 @@ npm run format         # Prettier formatting
 ```
 
 ### Documentation
+
 ```bash
 npm run docs:dev       # Start VitePress dev server (localhost:5173)
 npm run docs:build     # Build static documentation
 npm run docs:preview   # Preview built docs
 ```
 
 ### Running Single Tests
+
 ```bash
 npm test -- path/to/file.test.ts           # Run specific test file
 npm test -- --run                          # Run once without watch mode
@@ -57,6 +62,7 @@ npm test -- --coverage --run              # Coverage report without watch
 ## Architecture
 
 ### LangGraph Workflow Pipeline
+
 The engine uses a linear LangGraph state machine defined in `src/graph/auralyze-graph.ts`:
 
 ```
@@ -66,6 +72,7 @@ START → validateInput → metadataStep → analysisStep → feedbackStep → f
 Each node processes the shared `EngineState` and returns partial updates. If any node encounters an error, it sets `state.error` and subsequent nodes skip processing.
 
 ### Dependency Injection Pattern
+
 The engine uses **dependency injection** exclusively - it never makes HTTP requests or runs ffmpeg directly. Instead, host applications inject three client implementations:
 
 1. `audioMetadataClient: AudioMetadataClient` - Retrieves file metadata (duration, format, sample rate, etc.)
@@ -75,25 +82,30 @@ The engine uses **dependency injection** exclusively - it never makes HTTP reque
 The built-in `OpenAIFeedbackClient` (in `src/config/llm.ts`) implements `FeedbackClient` using the OpenAI SDK. Custom implementations can support other LLM providers.
 
 ### State Management
+
 State is defined using Zod schemas in `src/state.ts`. The `EngineState` type includes:
+
 - Session metadata (`sessionId`, `uploadUrl`, `userContext`)
 - File information (`fileInfo: FileInfo`)
 - Analysis results (`analysis: Analysis` with loudness, dynamics, spectrum, stereo sub-schemas)
 - LLM feedback (`feedbackText`, `suggestions`)
 - Error tracking (`error`)
 
 ### Entry Point
+
 The main API is `runAuralyzeSession(input, deps)` exported from `src/index.ts`. It builds the LangGraph workflow, initializes state, and invokes the compiled graph.
 
 ## Testing Strategy
 
 Tests use Vitest with mocked dependencies:
+
 - **Unit tests**: Individual node functions with `vi.fn()` mocks
 - **Integration tests**: Full graph execution with fake clients
 - **Schema tests**: Zod validation edge cases
 - **Prompt tests**: Feedback prompt builder output
 
 Test files follow the pattern: `test/<area>/<file>.<kind>.test.ts`
+
 - Example: `test/graph/auralyzeGraph.unit.test.ts`
 - Example: `test/graph/auralyzeGraph.integration.test.ts`
 
@@ -136,6 +148,7 @@ Only `dist/`, `README.md`, and `LICENSE` are included in the published package (
 ## Documentation Deployment
 
 The VitePress docs are automatically deployed via `.github/workflows/docs.yml` on pushes to `main`. The workflow:
+
 1. Builds the docs site
 2. Force-pushes to a companion repository (default: `auralyze/engine-docs` on `gh-pages` branch)
 3. Requires `DOCS_PUBLISH_TOKEN` secret with appropriate permissions