Onboard repository to Copilot coding agent with comprehensive documentation and robust Nix environment sourcing workflow

.github/copilot-instructions.md

@@ -0,0 +1,230 @@
+# Copilot Instructions for toolkit-dev/api
+
+## Repository Overview
+
+**Toolkit** is a TypeScript library that provides everything needed to build end-to-end typesafe APIs. The slogan is "define once, and ship with confidence." It's a monorepo containing multiple packages for JSON:API and OpenAPI support, along with React Query integrations and examples.
+
+**Key Details:**
+
+- **Language:** TypeScript/JavaScript (ESM modules only)
+- **Package Manager:** pnpm with workspaces
+- **Build System:** TypeScript compiler, Nix flake for environment
+- **Primary Tools:** Hono (HTTP server), Zod (validation), React Query
+- **Repository Size:** ~15 packages across JSON:API, OpenAPI, React Query, and examples
+- **Target Runtime:** Node.js 22
+
+## Environment Setup
+
+### Prerequisites
+
+This repository requires Nix for development environment management. **If you are an AI coding agent, see [AGENTS.md](AGENTS.md) for critical requirements about command execution.**
+
+**All commands must be prefixed with `nix develop --command`** to access the development environment. This prefix provides Node.js 22, pnpm 10, and all development tools.
+
+**Pattern:** `nix develop --command <your-command>`
+
+In command examples below, this prefix is shown explicitly.
+
+### Initial Setup
+
+1. **Start development environment:**
+
+   ```bash
+   nix develop --command bash
+   ```
+
+   - Takes 30-90 seconds on first run to download and configure environment
+   - Provides all development tools
+
+2. **Install dependencies:**
+
+   ```bash
+   nix develop --command pnpm install
+   ```
+
+   - Takes ~30-60 seconds on first run
+   - Creates node_modules and sets up husky git hooks
+
+3. **Compile TypeScript** (required before running most commands):
+   ```bash
+   nix develop --command pnpm -r run compile
+   ```
+   - Compiles all packages in dependency order
+
+## Build & Development
+
+### Common Commands
+
+**Development server:**
+
+```bash
+nix develop --command pnpm run dev
+```
+
+- Runs turbowatch for file watching and auto-compilation
+- Starts example backend server on http://localhost:3000
+- Rebuilds on TypeScript config changes
+
+**Lint code:**
+
+```bash
+nix develop --command pnpm run lint
+```
+
+- Uses ESLint with neostandard config
+- Must pass before commits (enforced by husky pre-commit hooks)
+
+**Format code:**
+
+```bash
+nix develop --command pnpm run format
+```
+
+- Uses Prettier for code formatting
+- Applied automatically on git commit via lint-staged
+
+**Clean build artifacts:**
+
+```bash
+nix develop --command pnpm run clean        # Clean all
+nix develop --command pnpm run clean:cache  # Clean dist folders only
+nix develop --command pnpm run clean:deps   # Clean node_modules only
+```
+
+**Run specific package commands:**
+
+```bash
+nix develop --command pnpm --filter @toolkit-dev/examples-backend run start
+```
+
+**Test specific packages:**
+
+```bash
+nix develop --command pnpm --filter @toolkit-dev/examples-backend run test
+```
+
+### Development Workflow
+
+1. Make changes to code
+2. Compile if needed: `nix develop --command pnpm -r run compile`
+3. Lint frequently: `nix develop --command pnpm run lint`
+4. Test individual packages: `nix develop --command pnpm --filter <package-name> run test`
+5. Run example server: `nix develop --command pnpm --filter @toolkit-dev/examples-backend run start`
+6. Commit (pre-commit hooks will run Prettier and ESLint automatically)
+
+### Common Development Patterns
+
+**Working with specific packages:**
+```bash
+# Navigate to specific package (optional, commands work from root)
+cd packages/jsonapi/jsonapi-types
+
+# Compile single package
+nix develop --command pnpm --filter @jsonapi/types run compile
+
+# Lint single package  
+nix develop --command pnpm --filter @jsonapi/types run lint
+```
+
+**Multi-package workflows:**
+```bash
+# Compile all packages in dependency order
+nix develop --command pnpm -r run compile
+
+# Clean and rebuild everything
+nix develop --command pnpm run clean && nix develop --command pnpm install && nix develop --command pnpm -r run compile
+```
+
+## Project Architecture
+
+### Package Structure
+
+View current packages:
+
+```bash
+nix develop --command find packages -name "package.json" -exec dirname {} \;
+```
+
+**Package Categories:**
+- **jsonapi/**: JSON:API implementation packages (types, parser, serializer, zod integration)
+- **openapi/**: OpenAPI implementation packages (core, client, server, document validation)
+- **react-query/**: React Query integrations for both JSON:API and fetch-based APIs
+- **runtime/**: Core runtime utilities (error handling, etc.)
+- **examples/**: Example applications (backend server, frontend client)
+
+**Workspace dependencies:** Packages use `workspace:*` for internal dependencies
+
+### Key Configuration Files
+
+- `flake.nix`: Nix development environment (Node.js 22, pnpm 10)
+- `pnpm-workspace.yaml`: pnpm workspace configuration
+- `tsconfig.json`: TypeScript project references and build config
+- `tsconfig.options.json`: Shared TypeScript compiler options
+- `eslint.config.js`: ESLint configuration using neostandard
+- `lint-staged.config.js`: Pre-commit formatting and linting
+- `turbowatch.ts`: File watching and development server configuration
+- `.envrc`: direnv integration (loads Nix automatically)
+
+### Development Tools
+
+- **DevContainer:** Available at `.devcontainer/devcontainer.json` using Nix container
+- **VSCode:** Settings in `.vscode/` configure Nix formatter and format-on-save
+- **Pre-commit Hooks:** Husky runs lint-staged (prettier + eslint) on commits
+
+### CI/CD Pipeline
+
+- **GitHub Actions:** `.github/workflows/run_test.yml` (uses shared workflow)
+- **Copilot Setup:** `.github/workflows/copilot-setup-steps.yml` installs Nix and dependencies
+- **Renovate:** Automated dependency updates via `.github/renovate.json5`
+
+## Troubleshooting
+
+### Validation Commands
+
+If you encounter issues, verify the environment with these commands:
+
+**Check linting:**
+
+```bash
+nix develop --command pnpm run lint
+```
+
+**Check TypeScript compilation:**
+
+```bash
+nix develop --command pnpm -r run compile
+```
+
+**Verify example server:**
+
+```bash
+nix develop --command pnpm --filter @toolkit-dev/examples-backend run start
+```
+
+Server should start on port 3000.
+
+**Test specific package functionality:**
+
+```bash
+nix develop --command pnpm --filter @toolkit-dev/examples-backend run test
+```
+
+### Common Issues
+
+- **Command not found errors:** Ensure you're using the `nix develop --command` prefix
+- **Husky pre-commit failures:** Git hooks require the Nix environment; ensure the prefix is used
+- **Missing dependencies:** Run `nix develop --command pnpm install`
+
+## For AI Coding Agents
+
+**See [AGENTS.md](../AGENTS.md) for critical requirements about working with the Nix environment.**
+
+Key points:
+
+- Every command must use `nix develop --command` prefix
+- This applies to all operations: pnpm, git, node, npm, etc.
+- No exceptions to this requirement
+
+<tool_calling>
+You have the capability to call multiple tools in a single response. For maximum efficiency, whenever you need to perform multiple independent operations, ALWAYS invoke all relevant tools simultaneously rather than sequentially. Especially when exploring repository, reading files, viewing directories, validating changes or replying to comments.
+</tool_calling>

AGENTS.md

@@ -0,0 +1,144 @@
+# Agent Development Guidelines
+
+This document provides critical environment requirements for AI coding agents (GitHub Copilot, Cursor, Aider, Cody, etc.) working with this repository.
+
+**For complete operational guidance** on working with this codebase (build commands, architecture, workflows), see [copilot-instructions.md](copilot-instructions.md).
+
+## Critical Requirement: Nix Environment
+
+This repository uses Nix for development environment management. All development tools (Node.js, pnpm, git hooks) are provided through Nix.
+
+### Command Execution Requirement
+
+**EVERY bash command you execute must use the `nix develop --command` prefix.**
+
+This is not optional. It applies to:
+
+- Package management: `pnpm install`, `pnpm run`, `npm`
+- Version control: `git add`, `git commit`, `git status`
+- Node.js: `node`, `npm`, `npx`
+- Build tools: `tsc`, custom scripts
+- File operations when they interact with the environment
+- **Everything** - no exceptions
+
+### Command Pattern
+
+```bash
+nix develop --command <your-command>
+```
+
+### Examples
+
+```bash
+# Package management
+nix develop --command pnpm install
+nix develop --command pnpm run dev
+nix develop --command pnpm run lint
+
+# Version control
+nix develop --command git status
+nix develop --command git add .
+nix develop --command git commit -m "implement feature"
+
+# TypeScript compilation
+nix develop --command pnpm -r run compile
+
+# Running specific packages
+nix develop --command pnpm --filter @toolkit-dev/examples-backend run start
+```
+
+## Why This Approach Is Required
+
+1. **Environment Isolation:** Node.js 22 and pnpm 10 are only available inside the Nix environment
+2. **Git Hooks:** Husky pre-commit hooks need pnpm to run lint-staged. Without the prefix, git commits will fail
+3. **Consistent Tooling:** Ensures all agents use the exact same tool versions
+4. **No System Dependencies:** The host system may not have Node.js or pnpm installed
+
+### What Happens Without the Prefix
+
+```bash
+# WRONG - Will fail - pnpm not found
+pnpm install
+
+# WRONG - Will fail - git hooks can't find pnpm
+git commit -m "changes"
+
+# CORRECT - Will succeed
+nix develop --command pnpm install
+nix develop --command git commit -m "changes"
+```
+
+## Environment Verification
+
+If you encounter issues, verify the environment is working correctly:
+
+```bash
+# Check tool versions
+nix develop --command node --version    # Should show v22.x.x
+nix develop --command pnpm --version    # Should show 10.x.x
+nix develop --command git --version     # Should work
+
+# Test git hooks work correctly
+nix develop --command bash -c "echo 'test' > test.txt"
+nix develop --command git add test.txt
+nix develop --command git commit -m "test commit"  # Should trigger husky hooks
+nix develop --command git reset --soft HEAD~1      # Undo test commit
+nix develop --command git reset HEAD test.txt      # Unstage
+nix develop --command rm test.txt                  # Clean up
+```
+
+## Important Notes for AI Agents
+
+### Do Not Install Nix
+
+The hosting environment (GitHub Codespaces, local devcontainer, etc.) provides Nix. Never attempt to install Nix yourself.
+
+### Remember This Pattern
+
+Your agent must consistently remember and apply the `nix develop --command` prefix. This is the single most important requirement for working with this repository.
+
+### Error Recovery
+
+If you see errors like:
+
+- "command not found: pnpm"
+- "command not found: node"
+- Git commit hooks failing
+
+The solution is always: ensure you're using the `nix develop --command` prefix.
+
+### Shell Context
+
+You may need to enter a persistent Nix shell for interactive work:
+
+```bash
+nix develop --command bash
+# Now inside Nix shell, commands work without prefix
+pnpm install
+git status
+exit  # Leave Nix shell
+```
+
+However, for individual commands in automated workflows, always use the prefix pattern.
+
+## Integration with Repository Workflows
+
+The [copilot-instructions.md](./.github/copilot-instructions.md) file contains all workflow details:
+
+- Complete build and development commands
+- Package structure and architecture
+- Linting and formatting requirements
+- CI/CD pipeline information
+- Troubleshooting guidance
+
+This file focuses solely on the Nix environment constraint. Refer to copilot-instructions.md for everything else.
+
+## Quick Reference
+
+**Every command pattern:**
+
+```bash
+nix develop --command <any-command-here>
+```
+
+**No exceptions. Always use the prefix.**