docs: developer experience improvements

CLAUDE.md

@@ -13,6 +13,37 @@ npm run dev          # Router (webhook receiver, requires Redis)
 npm run dev:web      # Dashboard frontend (separate terminal)
 ```
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Development](#development)
+  - [Testing](#testing)
+  - [Linting](#linting)
+  - [Git Hooks](#git-hooks)
+- [Key Directories](#key-directories)
+- [Environment Variables](#environment-variables)
+- [Database Configuration](#database-configuration)
+  - [Schema](#schema)
+  - [Database Scripts](#database-scripts)
+  - [Migration Workflow](#migration-workflow)
+  - [Credentials](#credentials)
+  - [Credential Encryption at Rest](#credential-encryption-at-rest)
+  - [GitHub Dual-Persona Model](#github-dual-persona-model)
+  - [Webhook Signature Verification](#webhook-signature-verification)
+  - [Integration Credential Resolution](#integration-credential-resolution)
+  - [Agent Trigger Configuration](#agent-trigger-configuration)
+  - [Review Agent Trigger Modes](#review-agent-trigger-modes)
+  - [PM Agent Trigger Modes](#pm-agent-trigger-modes)
+- [Claude Code Engine](#claude-code-engine)
+- [Codex Engine](#codex-engine)
+- [Dashboard](#dashboard)
+- [CLI (`cascade`)](#cli-cascade)
+- [Adding New Triggers](#adding-new-triggers)
+- [Adding New Agents](#adding-new-agents)
+- [Agent Resilience Features](#agent-resilience-features)
+- [Debugging Production Sessions](#debugging-production-sessions)
+
 ## Architecture
 
 CASCADE runs as three services (no monolithic server mode):

CONTRIBUTING.md

@@ -30,20 +30,35 @@ Thank you for your interest in contributing to Cascade! This guide will help you
    npm run db:migrate
    ```
 
-5. **Start Redis** (required for the router):
+5. **Build the project**:
+   ```bash
+   npm run build
+   ```
+
+6. **Start Redis** (required for the router):
    ```bash
    # macOS
    brew install redis && brew services start redis
    # Or use the setup script
    .cascade/setup.sh
    ```
 
-6. **Run the development servers**:
+7. **Run the development servers**:
+
+   Start all services in one terminal:
+   ```bash
+   npm run dev:all      # Router + Dashboard API + Frontend (color-coded output)
+   ```
+
+   Or start each service in a separate terminal:
    ```bash
-   npm run dev          # Router (webhook receiver)
-   npm run dev:web      # Dashboard frontend (separate terminal)
+   npm run dev                                           # Router (:3000)
+   node --env-file=.env dist/dashboard.js               # Dashboard API (:3001)
+   npm run dev:web                                       # Frontend (Vite, :5173)
    ```
 
+   > **Note:** The Dashboard API must be running for the frontend to show data. The Vite dev server proxies `/trpc` and `/api` to `localhost:3001`.
+
 ## Running Tests
 
 ```bash
@@ -93,9 +108,7 @@ This is enforced by commitlint via lefthook pre-commit hooks.
 
 3. **Ensure all checks pass**:
    ```bash
-   npm run lint
-   npm run typecheck
-   npm test
+   npm run verify   # runs lint + typecheck + unit tests in one command
    ```
 
 4. **Open a PR** targeting the `dev` branch. PRs to `main` must come from `dev` (enforced by CI).
@@ -121,16 +134,46 @@ See [CLAUDE.md](./CLAUDE.md) for a detailed architecture overview. Key directori
 
 ## Adding New Agents
 
-1. Create the agent in `src/agents/`
-2. Define its system prompt in `src/agents/prompts/`
-3. Register it in the agent registry
+Agents are defined using YAML definition files. Built-in definitions live in `src/agents/definitions/`.
+
+1. **Write a YAML definition** — model your file on an existing one in `src/agents/definitions/` (e.g. `implementation.yaml`)
+2. **Import the definition**:
+   ```bash
+   cascade definitions import --file my-agent.yaml
+   ```
+   Or use the **Agent Definitions** tab in the dashboard.
+3. **Create an `agent_configs` row** to enable the agent for a project:
+   ```bash
+   cascade agents create --agent-type my-agent --project-id <project-id>
+   ```
+4. **Discover available triggers** for the new agent type:
+   ```bash
+   cascade projects trigger-discover --agent my-agent   # see available events
+   ```
+
+5. **Configure triggers** — enable the events that should activate the agent:
+   ```bash
+   cascade projects trigger-set <project-id> --agent my-agent --event pm:status-changed --enable
+   ```
 
 ## The `.cascade/` Directory
 
 When Cascade works on a repository, it looks for a `.cascade/` directory at the root of that repo. This directory lets you customize agent behavior — setup scripts, post-edit hooks, test runners, and environment variables.
 
 See **[`.cascade/` Directory Guide](./docs/cascade-directory.md)** for the full reference.
 
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `Cannot connect to Redis` | Redis not running | `redis-server` or `brew services start redis` |
+| `ECONNREFUSED 5432` | PostgreSQL not running | `pg_ctl start` or start Docker |
+| `dist/ not found` when running CLI | Build needed | `npm run build` |
+| Frontend shows no data | Dashboard API not running | `node --env-file=.env dist/dashboard.js` |
+| Node version error | Node < 22 | Install Node 22+ (`nvm use 22`) |
+| Integration tests silently skip | No test database | `npm run test:db:up` first |
+| `commitlint` hook fails | Non-conventional commit message | Use format `feat(scope): description` |
+
 ## Getting Help
 
 - Open an [issue](https://github.com/mongrel-intelligence/cascade/issues) for bugs or feature requests

README.md

@@ -2,6 +2,8 @@
 
 [![CI](https://github.com/mongrel-intelligence/cascade/actions/workflows/ci.yml/badge.svg)](https://github.com/mongrel-intelligence/cascade/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/mongrel-intelligence/cascade/graph/badge.svg)](https://codecov.io/gh/mongrel-intelligence/cascade)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
 
 > **Cascade orchestrates AI agents (Claude Code, Codex, opencode, LLMist) across your workflows in GitHub, Trello, and Jira.**
 
@@ -89,15 +91,22 @@ cp .env.example .env    # Set DATABASE_URL and REDIS_URL
 npm run db:migrate
 ```
 
-Start each service in a separate terminal:
+Start all three services with one command (requires a build first):
 
 ```bash
-npm run dev                                           # Router (webhook receiver, :3000)
-npm run build && node --env-file=.env dist/dashboard.js  # Dashboard API (:3001)
-npm run dev:web                                       # Dashboard frontend (Vite, :5173)
+npm run build
+npm run dev:all   # Router + Dashboard API + Frontend, color-coded output
 ```
 
-> **Note:** The Vite dev server proxies `/trpc` and `/api` to `localhost:3001`, so the Dashboard API must be running for the frontend to work. See [CLAUDE.md](./CLAUDE.md#running-the-dashboard) for more details.
+Or start each service in a separate terminal:
+
+```bash
+npm run dev                                        # Router (:3000)
+node --env-file=.env dist/dashboard.js             # Dashboard API (:3001)
+npm run dev:web                                    # Frontend (Vite, :5173)
+```
+
+> **Note:** The Vite dev server proxies `/trpc` and `/api` to `localhost:3001`, so the Dashboard API must be running for the frontend to work.
 
 ### Commands
 
@@ -111,6 +120,8 @@ npm run dev:web                                       # Dashboard frontend (Vite
 | `npm run build` | Compile TypeScript to `dist/` |
 | `npm run db:migrate` | Apply pending migrations |
 | `npm run db:studio` | Open Drizzle Studio |
+| `npm run dev:all` | Start all services (router + dashboard + frontend) |
+| `npm run verify` | Lint + typecheck + unit tests (pre-PR check) |
 
 ---
 
@@ -156,7 +167,7 @@ For deeper documentation on all of these topics, see [CLAUDE.md](./CLAUDE.md).
 
 1. Fork the repository and create a feature branch from `dev`
 2. Make your changes with tests (`npm test`)
-3. Ensure lint and typecheck pass (`npm run lint && npm run typecheck`)
+3. Ensure all checks pass (`npm run verify`)
 4. Open a pull request — Cascade will review its own PRs if configured to do so
 
 Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.