DOCUMENTATION_INDEX.md

Documentation Index

Complete guide to all ai-kit documentation.

Quick Start

New to ai-kit? Start here:

1. README.md - Project overview and quick start
2. CONTRIBUTING.md - Development guide
3. Setup Guide - Platform-specific instructions

Core Documentation

Getting Started

• README.md - Project overview, quick start, technology stack
• CONTRIBUTING.md - Complete contributor guide
• VERSIONS.md - Tool versions and update policy

Setup & Configuration

• Platform-Specific Setup - macOS, Linux, Windows, Docker
• TURBOREPO.md - Turborepo configuration explained
• .python-version - Python version (3.12.10)
• package.json - Node.js and pnpm versions

Development Workflow

• justfile - Available commands (just --list)
• pyproject.toml - Python workspace configuration
• turbo.json - Turborepo pipeline configuration

Troubleshooting Guides

Common Issues

• CI Troubleshooting - Lint, format, test, dependency issues
• Virtual Environment Issues - .venv problems and edge cases
• Turborepo Issues - Cache corruption and performance

Maintenance

• Updating Dependencies - Python, Node.js, tool updates
• CI Testing Guide - Testing CI failures

Package Documentation

Applications (apps/)

• CLI App - Command-line interface
• Apps Overview - What goes in apps/

Libraries (packages/)

• Core Library - Core functionality
• Packages Overview - What goes in packages/

Validation & Quality

• VALIDATION.md - Success criteria validation results
• .pre-commit-config.yaml - Pre-commit hooks configuration
• .github/workflows/ci.yml - CI pipeline
• .github/workflows/pre-commit.yml - Pre-commit validation

Specification Documents

Located in specs/001-setup-developer-experience/:

• spec.md - Feature specification
• plan.md - Implementation plan
• tasks.md - Task breakdown
• research.md - Research findings
• quickstart.md - Quick reference

Documentation by Role

New Contributors

1. README.md - Start here
2. CONTRIBUTING.md - How to contribute
3. Platform-Specific Setup - Install tools
4. CI Troubleshooting - Fix common issues

Active Developers

1. CONTRIBUTING.md - Development workflow
2. TURBOREPO.md - Understanding Turborepo
3. Updating Dependencies - Maintenance
4. Virtual Environment Issues - Debug .venv

Maintainers

1. VERSIONS.md - Version management
2. VALIDATION.md - Quality metrics
3. CI Testing Guide - CI validation
4. Specification Documents - Feature details

Documentation by Topic

Setup & Installation

• README.md - Quick start
• Platform-Specific Setup - Detailed setup
• VERSIONS.md - Tool versions

Development

• CONTRIBUTING.md - Development guide
• justfile - Commands
• TURBOREPO.md - Monorepo orchestration

Troubleshooting

• CI Troubleshooting - CI issues
• Virtual Environment Issues - .venv problems
• Turborepo Issues - Cache issues

Maintenance

• Updating Dependencies - Updates
• VERSIONS.md - Version policy

Quality Assurance

• VALIDATION.md - Success criteria
• CI Testing Guide - Testing

Quick Reference

Common Commands

just --list          # List all commands
just setup           # Initial setup
just lint            # Run linting
just format          # Format code
just test            # Run tests
just build           # Build packages
just clean           # Clean artifacts
just cache-clear     # Clear Turborepo cache

Tool Versions

• Python: 3.12.10
• Node.js: 22.14.0
• pnpm: 10.18.2
• uv: 0.7.x+
• ruff: 0.14.0
• Turborepo: 2.5.8

Important Files

• .python-version - Python version
• pyproject.toml - Python workspace
• package.json - Node.js config
• turbo.json - Turborepo pipeline
• justfile - Commands
• uv.lock - Python dependencies
• pnpm-lock.yaml - Node.js dependencies

Documentation Standards

All documentation follows these standards:

• ✅ Clear structure with table of contents
• ✅ Searchable headings
• ✅ Step-by-step instructions
• ✅ Code examples
• ✅ Troubleshooting sections
• ✅ Cross-references to related docs

Contributing to Documentation

See CONTRIBUTING.md for:

• Documentation style guide
• How to update docs
• Where to add new documentation

Getting Help

Can't find what you need?

1. Search this index
2. Check CONTRIBUTING.md troubleshooting
3. Search GitHub Issues
4. Ask in GitHub Discussions

Documentation Checklist

For new features, ensure documentation includes:

• README.md update (if user-facing)
• CONTRIBUTING.md update (if workflow changes)
• Troubleshooting guide (for common issues)
• Version updates (VERSIONS.md)
• Validation results (VALIDATION.md)
• This index (if new doc added)