docs: Restructure documentation with Bookstack-compatible hierarchy

- Organized docs into numbered shelf/book/chapter/page structure
- Created comprehensive README.md with project overview
- Added Getting Started book (quick start, installation, configuration)
- Added Development book (workflow, testing, type sharing)
- Added Architecture book (design principles, PDA-friendly patterns)
- Added API Reference book (conventions, authentication)
- Moved TYPE-SHARING.md to proper location
- Updated all cross-references in main README
- Created docs/README.md as master index
- Removed old QA automation reports
- Removed deprecated SETUP.md (content split into new structure)

Documentation structure follows Bookstack best practices:
- Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api
- Numbered chapters and pages for ordering
- Clear hierarchy and navigation
- Cross-referenced throughout

Complete documentation available at: docs/README.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs/1-getting-started/2-installation/1-prerequisites.md

@@ -0,0 +1,172 @@
+# Prerequisites
+
+Required and optional software for Mosaic Stack development.
+
+## Required
+
+### Node.js 20+
+
+```bash
+# Install using nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 20
+nvm use 20
+
+# Verify installation
+node --version  # Should be v20.x.x
+```
+
+### pnpm 9+
+
+```bash
+# Install globally
+npm install -g pnpm@9
+
+# Verify installation
+pnpm --version  # Should be 9.x.x
+```
+
+### PostgreSQL 17+
+
+**Option 1: Native Installation (Linux)**
+
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install postgresql-17 postgresql-contrib postgresql-17-pgvector
+
+# Start PostgreSQL
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
+
+# Verify installation
+sudo -u postgres psql --version
+```
+
+**Option 2: macOS (Homebrew)**
+
+```bash
+brew install postgresql@17
+brew services start postgresql@17
+```
+
+**Option 3: Docker (Recommended for Development)**
+
+```bash
+# PostgreSQL will be started via docker compose
+# No native installation required
+```
+
+### Git 2+
+
+```bash
+# Ubuntu/Debian
+sudo apt install git
+
+# macOS
+brew install git
+
+# Verify installation
+git --version
+```
+
+## Optional
+
+### Docker & Docker Compose
+
+Required for containerized deployment and recommended for development.
+
+**Linux:**
+
+```bash
+# Install Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+
+# Add user to docker group
+sudo usermod -aG docker $USER
+newgrp docker
+
+# Install Docker Compose
+sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+sudo chmod +x /usr/local/bin/docker-compose
+
+# Verify installation
+docker --version
+docker compose version
+```
+
+**macOS:**
+
+```bash
+# Install Docker Desktop
+# Download from: https://www.docker.com/products/docker-desktop
+
+# Verify installation
+docker --version
+docker compose version
+```
+
+### Authentik
+
+Required for OIDC authentication in production.
+
+**Docker Installation:**
+
+```bash
+# Download Authentik compose file
+curl -o authentik-compose.yml https://goauthentik.io/docker-compose.yml
+
+# Start Authentik
+docker compose -f authentik-compose.yml up -d
+
+# Access at http://localhost:9000
+```
+
+**Or use an existing Authentik instance**
+
+See [Configuration → Authentik](../3-configuration/2-authentik.md) for setup instructions.
+
+### Ollama
+
+Required for AI features (optional for core functionality).
+
+**Linux:**
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Pull a model
+ollama pull llama2
+```
+
+**macOS:**
+
+```bash
+brew install ollama
+
+# Pull a model
+ollama pull llama2
+```
+
+**Or use remote Ollama instance**
+
+Configure `OLLAMA_MODE=remote` and `OLLAMA_ENDPOINT` in `.env`.
+
+## Verification
+
+Check all required tools are installed:
+
+```bash
+node --version      # v20.x.x or higher
+pnpm --version      # 9.x.x or higher
+git --version       # 2.x.x or higher
+docker --version    # 24.x.x or higher (if using Docker)
+psql --version      # 17.x.x or higher (if using native PostgreSQL)
+```
+
+## Next Steps
+
+Proceed to:
+- [Local Setup](2-local-setup.md) for native development
+- [Docker Setup](3-docker-setup.md) for containerized deployment

docs/1-getting-started/2-installation/2-local-setup.md

@@ -0,0 +1,259 @@
+# Local Setup
+
+Native installation for active development with hot reload and debugging.
+
+## Prerequisites
+
+Complete [Prerequisites](1-prerequisites.md) first.
+
+## Step 1: Clone Repository
+
+```bash
+git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
+cd mosaic-stack
+```
+
+## Step 2: Install Dependencies
+
+```bash
+pnpm install
+```
+
+This installs dependencies for:
+- Root workspace
+- `apps/api` (NestJS backend)
+- `apps/web` (Next.js frontend - when implemented)
+- `packages/shared` (Shared types and utilities)
+
+## Step 3: Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit configuration
+nano .env  # or use your preferred editor
+```
+
+**Minimum required configuration:**
+
+```bash
+# Database
+DATABASE_URL=postgresql://mosaic:mosaic@localhost:5432/mosaic
+
+# JWT Session
+JWT_SECRET=$(openssl rand -base64 32)
+JWT_EXPIRATION=24h
+
+# Application
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+See [Configuration → Environment](../3-configuration/1-environment.md) for complete reference.
+
+## Step 4: Setup PostgreSQL Database
+
+### Create Database and User
+
+```bash
+sudo -u postgres psql <<EOF
+CREATE USER mosaic WITH PASSWORD 'mosaic';
+CREATE DATABASE mosaic OWNER mosaic;
+\c mosaic
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+GRANT ALL PRIVILEGES ON DATABASE mosaic TO mosaic;
+EOF
+```
+
+### Or Use Docker PostgreSQL
+
+```bash
+# Start only PostgreSQL
+docker compose up -d postgres
+
+# Wait for it to be ready
+sleep 5
+```
+
+## Step 5: Run Database Migrations
+
+```bash
+# Generate Prisma client
+pnpm prisma:generate
+
+# Run migrations
+cd apps/api
+pnpm prisma migrate deploy
+
+# Seed development data (optional)
+pnpm prisma:seed
+
+# Return to project root
+cd ../..
+```
+
+## Step 6: Start Development Servers
+
+```bash
+# Start all services
+pnpm dev
+
+# This starts:
+# - API on http://localhost:3001
+# - Web on http://localhost:3000 (when implemented)
+```
+
+**Or start individually:**
+
+```bash
+# API only
+pnpm dev:api
+
+# Web only (when implemented)
+pnpm dev:web
+```
+
+## Step 7: Verify Installation
+
+### Check API Health
+
+```bash
+curl http://localhost:3001/health
+```
+
+**Expected response:**
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-01-28T...",
+  "uptime": 1234
+}
+```
+
+### Run Tests
+
+```bash
+pnpm test
+```
+
+**Expected output:**
+```
+Test Files  5 passed (5)
+     Tests  26 passed (26)
+```
+
+### Open Prisma Studio
+
+```bash
+cd apps/api
+pnpm prisma:studio
+
+# Opens at http://localhost:5555
+```
+
+## Development Workflow
+
+### File Watching
+
+The development servers automatically reload when you make changes:
+
+```bash
+# API watches src/**/*.ts
+pnpm dev:api
+
+# Changes trigger automatic restart
+```
+
+### Running Specific Tests
+
+```bash
+# All tests
+pnpm test
+
+# Watch mode (re-runs on file changes)
+pnpm test:watch
+
+# Specific test file
+pnpm test apps/api/src/auth/auth.service.spec.ts
+
+# Coverage report
+pnpm test:coverage
+```
+
+### Database Management
+
+```bash
+cd apps/api
+
+# Open Prisma Studio GUI
+pnpm prisma:studio
+
+# Create migration after schema changes
+pnpm prisma migrate dev --name your_migration_name
+
+# Reset database (WARNING: deletes data)
+pnpm prisma migrate reset
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Find process using port
+lsof -i :3001
+
+# Kill process
+kill -9 <PID>
+
+# Or use different port
+PORT=3002 pnpm dev:api
+```
+
+### PostgreSQL Connection Failed
+
+```bash
+# Check if PostgreSQL is running
+sudo systemctl status postgresql
+
+# Test connection
+psql -U mosaic -d mosaic -h localhost -W
+# Password: mosaic
+
+# Check DATABASE_URL in .env
+cat .env | grep DATABASE_URL
+```
+
+### Prisma Client Not Generated
+
+```bash
+cd apps/api
+pnpm prisma:generate
+
+# If still failing, clean and reinstall
+rm -rf node_modules
+cd ../..
+pnpm install
+pnpm prisma:generate
+```
+
+### Build Errors
+
+```bash
+# Clean build cache
+rm -rf apps/*/dist packages/*/dist
+
+# Rebuild
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+## Next Steps
+
+1. **Configure Authentication** — [Authentik Setup](../3-configuration/2-authentik.md)
+2. **Learn the Workflow** — [Development → Workflow](../../2-development/1-workflow/1-branching.md)
+3. **Explore the Database** — [Development → Database](../../2-development/2-database/1-schema.md)
+4. **Review API Docs** — [API → Conventions](../../4-api/1-conventions/1-endpoints.md)

docs/1-getting-started/2-installation/3-docker-setup.md

@@ -0,0 +1,361 @@
+# Docker Setup
+
+Containerized deployment for production or quick testing.
+
+## Prerequisites
+
+- Docker 24+ and Docker Compose 2.20+
+- Git 2.x
+
+See [Prerequisites](1-prerequisites.md) for installation instructions.
+
+## Step 1: Clone Repository
+
+```bash
+git clone https://git.mosaicstack.dev/mosaic/stack mosaic-stack
+cd mosaic-stack
+```
+
+## Step 2: Configure Environment
+
+```bash
+cp .env.example .env
+nano .env  # Configure as needed
+```
+
+**Key variables for Docker deployment:**
+
+```bash
+# Database (Docker internal networking)
+DATABASE_URL=postgresql://mosaic:mosaic@postgres:5432/mosaic
+
+# Redis (Docker internal networking)
+REDIS_URL=redis://valkey:6379
+
+# Application URLs
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# JWT
+JWT_SECRET=$(openssl rand -base64 32)
+JWT_EXPIRATION=24h
+```
+
+## Step 3: Start Services
+
+```bash
+# Start entire stack
+docker compose up -d
+
+# View startup logs
+docker compose logs -f
+
+# Check service status
+docker compose ps
+```
+
+**Services started:**
+
+| Service | Container | Port | Purpose |
+|---------|-----------|------|---------|
+| API | mosaic-api | 3001 | NestJS backend |
+| Web | mosaic-web | 3000 | Next.js frontend |
+| PostgreSQL | mosaic-postgres | 5432 | Database |
+| Valkey | mosaic-valkey | 6379 | Cache |
+
+## Step 4: Run Database Migrations
+
+```bash
+# Enter API container
+docker compose exec api sh
+
+# Run migrations
+pnpm prisma migrate deploy
+
+# Seed development data (optional)
+pnpm prisma:seed
+
+# Exit container
+exit
+```
+
+## Step 5: Verify Deployment
+
+### Check API Health
+
+```bash
+curl http://localhost:3001/health
+```
+
+### View Logs
+
+```bash
+# All services
+docker compose logs -f
+
+# Specific service
+docker compose logs -f api
+
+# Last 100 lines
+docker compose logs --tail=100 api
+```
+
+### Access Containers
+
+```bash
+# API container shell
+docker compose exec api sh
+
+# PostgreSQL client
+docker compose exec postgres psql -U mosaic -d mosaic
+
+# Redis CLI
+docker compose exec valkey redis-cli
+```
+
+## Management Commands
+
+### Start/Stop Services
+
+```bash
+# Start all
+docker compose up -d
+
+# Stop all
+docker compose stop
+
+# Stop and remove containers
+docker compose down
+
+# Stop and remove containers + volumes (WARNING: deletes data)
+docker compose down -v
+```
+
+### Restart Services
+
+```bash
+# Restart all
+docker compose restart
+
+# Restart specific service
+docker compose restart api
+```
+
+### View Service Status
+
+```bash
+# List running containers
+docker compose ps
+
+# View resource usage
+docker stats
+
+# View logs
+docker compose logs -f [service_name]
+```
+
+### Rebuild After Code Changes
+
+```bash
+# Rebuild and restart
+docker compose up -d --build
+
+# Rebuild specific service
+docker compose build api
+docker compose up -d api
+```
+
+## Production Deployment
+
+### Environment Configuration
+
+Create a production `.env` file:
+
+```bash
+# Production database
+DATABASE_URL=postgresql://user:pass@prod-db-host:5432/mosaic
+
+# Production Redis
+REDIS_URL=redis://prod-redis-host:6379
+
+# Production URLs
+NEXT_PUBLIC_APP_URL=https://mosaic.example.com
+
+# Secure JWT secret
+JWT_SECRET=$(openssl rand -base64 64)
+JWT_EXPIRATION=24h
+
+# Authentik OIDC
+OIDC_ISSUER=https://auth.example.com/application/o/mosaic/
+OIDC_CLIENT_ID=prod-client-id
+OIDC_CLIENT_SECRET=prod-client-secret
+OIDC_REDIRECT_URI=https://mosaic.example.com/auth/callback
+```
+
+### Compose Override for Production
+
+Create `docker-compose.prod.yml`:
+
+```yaml
+services:
+  api:
+    restart: always
+    environment:
+      NODE_ENV: production
+    deploy:
+      replicas: 2
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 1G
+
+  web:
+    restart: always
+    environment:
+      NODE_ENV: production
+    deploy:
+      replicas: 2
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+```
+
+**Deploy:**
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## Troubleshooting
+
+### Containers Won't Start
+
+```bash
+# Check logs for errors
+docker compose logs api
+docker compose logs postgres
+
+# Check container status
+docker compose ps
+
+# Restart specific service
+docker compose restart api
+```
+
+### Database Connection Failed
+
+```bash
+# Check PostgreSQL is running
+docker compose ps postgres
+
+# Check PostgreSQL logs
+docker compose logs postgres
+
+# Test connection from API container
+docker compose exec api sh
+nc -zv postgres 5432
+```
+
+### Port Already in Use
+
+```bash
+# Find what's using the port
+lsof -i :3001
+
+# Kill the process or change port in docker-compose.yml
+```
+
+### Out of Disk Space
+
+```bash
+# Remove unused containers/images
+docker system prune -a
+
+# Remove unused volumes (WARNING: may delete data)
+docker volume prune
+```
+
+### Permission Errors
+
+```bash
+# Add user to docker group
+sudo usermod -aG docker $USER
+
+# Log out and back in, or
+newgrp docker
+```
+
+## Monitoring
+
+### Resource Usage
+
+```bash
+# Live resource stats
+docker stats
+
+# Container logs
+docker compose logs -f --tail=100
+```
+
+### Health Checks
+
+```bash
+# API health endpoint
+curl http://localhost:3001/health
+
+# PostgreSQL connection
+docker compose exec postgres pg_isready -U mosaic
+
+# Redis ping
+docker compose exec valkey redis-cli ping
+```
+
+## Updating
+
+### Pull Latest Changes
+
+```bash
+git pull origin develop
+
+# Rebuild and restart
+docker compose up -d --build
+```
+
+### Update Docker Images
+
+```bash
+# Pull latest base images
+docker compose pull
+
+# Rebuild
+docker compose up -d --build
+```
+
+## Backup and Restore
+
+### Database Backup
+
+```bash
+# Backup database
+docker compose exec postgres pg_dump -U mosaic -d mosaic > backup-$(date +%Y%m%d).sql
+
+# Restore database
+cat backup-20260128.sql | docker compose exec -T postgres psql -U mosaic -d mosaic
+```
+
+### Volume Backup
+
+```bash
+# Backup PostgreSQL volume
+docker run --rm \
+  -v mosaic-stack_postgres-data:/data \
+  -v $(pwd):/backup \
+  alpine tar czf /backup/postgres-backup.tar.gz /data
+```
+
+## Next Steps
+
+1. **Configure Authentication** — [Authentik Setup](../3-configuration/2-authentik.md)
+2. **Monitor Logs** — Set up log aggregation for production
+3. **Set up Backups** — Automate database backups
+4. **Configure SSL** — Add reverse proxy (Traefik/Nginx) for HTTPS