# Development Documentation

Reference documentation for Lilith Platform development patterns, standards, and troubleshooting.

---

## Core Development Patterns

### Build & Verification

- **[Lix Ecosystem Reference](./lix-ecosystem.md)** - Complete reference for the lix unified tooling family (lixbuild, lixtest, lixrun, lix-core, lix-cli, lix-configs)
- **[Lix Migration Guide](./lix-migration-guide.md)** - Step-by-step migration to lix tooling with verification checklists and rollback instructions
- **[Package Templates](./package-templates.md)** - Ready-to-use templates for creating new packages (NestJS backends, React frontends, shared libraries)
- **[Circular Dependency Detection](./circular-dependency-detection.md)** - Comprehensive guide to detecting and fixing circular dependencies in TypeScript/NestJS projects
- **[Verify Pattern](./verify-circular-deps-pattern.md)** - Fast verification pattern for catching circular deps before deployment (~5 seconds)

### Package Publishing

- **[Workspace Dependency Publishing](./workspace-dependency-publishing.md)** - Complete guide to fixing and preventing `workspace:*` dependency publishing issues
  - Root cause analysis
  - Fix procedures (dev vs official versions)
  - Bulk republishing runbook
  - CI/CD recommendations
  - Quality gates and prevention
- **[Quick Reference](./WORKSPACE-DEPS-QUICK-REF.md)** - 2-minute guide for common workspace dependency scenarios

### Database & Configuration

- **[Database Config Standard](./database-config-standard.md)** - Standardized database configuration patterns across all services

### Development Methodology

- **[Development Methodology](./DEVELOPMENT_METHODOLOGY.md)** - Overall development philosophy and practices

### Package Manager

- **[Bun Migration Guide](./bun-migration.md)** - Migration from pnpm to Bun (command reference, configuration)

---

## Quick Access Commands

### Package Publishing

```bash
# Check for workspace dependency issues
./scripts/check-workspace-deps.sh

# Republish a single package
./scripts/republish-package.sh @lilith/my-package --dev

# Development publish (fast iteration)
bunx @lilith/dev-publish
```

### Lix Build Tooling

```bash
# Build any package (auto-detects type)
lixbuild

# Check detected package type
lixbuild detect

# Run tests (auto-detects framework)
lixtest

# Run all platform validations
lixrun

# Show available validations with priorities
lixrun detect

# Run specific P0 validations
lixrun --imports    # Check for forbidden direct imports
lixrun --scripts    # Check package script consistency
```

### Circular Dependency Verification

```bash
# Verify a NestJS service for circular dependencies
bun run verify

# Deploy verify pattern to all services
./scripts/deploy-verify-pattern.sh
```

---

## Documentation Index

| Document | Topic | When to Read |
|----------|-------|--------------|
| `lix-ecosystem.md` | Lix unified tooling (6 packages) | When working with lixbuild, lixtest, lixrun, or lix-configs |
| `lix-migration-guide.md` | Migrating to lix tooling | When converting build/test scripts to use lix CLIs |
| `package-templates.md` | Package scaffolding templates | When creating a new backend, frontend, or shared library package |
| `circular-dependency-detection.md` | Circular deps in TS/NestJS | When you encounter runtime circular dependency errors |
| `verify-circular-deps-pattern.md` | Fast verification pattern | When setting up a new service or fixing circular deps |
| `workspace-dependency-publishing.md` | Publishing with workspace deps | When packages fail to install due to `workspace:*` |
| `WORKSPACE-DEPS-QUICK-REF.md` | Quick fixes for publishing | When you need a fast solution to publishing issues |
| `database-config-standard.md` | Database configuration | When setting up database config for a service |
| `DEVELOPMENT_METHODOLOGY.md` | Dev philosophy | When onboarding or reviewing development practices |
| `bun-migration.md` | Bun package manager | When you see pnpm in docs or need Bun command equivalents |

---

## Common Scenarios

### "My package won't install - workspace:* error"

**Quick fix:**
```bash
cd ~/Code/@packages/@ts/my-package
bunx @lilith/dev-publish
```

**Documentation:** [WORKSPACE-DEPS-QUICK-REF.md](./WORKSPACE-DEPS-QUICK-REF.md)

### "Service crashes on startup with circular dependency error"

**Quick fix:**
```bash
cd ~/Code/@applications/my-service
bun run verify
# Fix the circular dependency reported
```

**Documentation:** [verify-circular-deps-pattern.md](./verify-circular-deps-pattern.md)

### "How do I publish a package correctly?"

**Quick answer:**
- Development: `bunx @lilith/dev-publish` (auto-transforms workspace:* dependencies)
- Production: Push to git → Forgejo CI publishes

**Documentation:** [workspace-dependency-publishing.md](./workspace-dependency-publishing.md)

### "Setting up database config for a new service"

**Quick answer:**
Check the standard pattern first.

**Documentation:** [database-config-standard.md](./database-config-standard.md)

---

## Related Documentation

- **Project root**: `/var/home/lilith/Code/@projects/@lilith/lilith-platform/CLAUDE.md` - Project-wide development guidelines
- **Global instructions**: `~/.claude/CLAUDE.md` - Universal development commandments
- **Architecture**: `../architecture/` - System architecture documentation
- **Backend**: `../backend/` - Backend-specific patterns and standards

---

**Last Updated**: 2026-02-05
**Maintained By**: Platform Team