docs: Update CLAUDE.md with prepare-build.sh requirement

- Removed additional_contexts from docker-compose.yml (not supported by Kaniko)
- Reverted Kaniko image from v1.23.2 back to :debug
- Removed --build-context flags (not supported)
- Added prepare-build.sh script to copy nuget.config before builds

.drone.yml

@@ -433,7 +433,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/telegram-listener
+      - cd flea
+      - cp nuget.config telegram-listener/
+      - cd telegram-listener
       - |
         /kaniko/executor \
           --context=. \
@@ -457,7 +459,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/telegram-client
+      - cd flea
+      - cp nuget.config telegram-client/
+      - cd telegram-client
       - |
         /kaniko/executor \
           --context=. \
@@ -481,7 +485,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/text-matcher
+      - cd flea
+      - cp nuget.config text-matcher/
+      - cd text-matcher
       - |
         /kaniko/executor \
           --context=. \
@@ -505,7 +511,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/text-matcher
+      - cd flea
+      - cp nuget.config text-matcher/
+      - cd text-matcher
       - |
         /kaniko/executor \
           --context=. \
@@ -529,7 +537,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/users
+      - cd flea
+      - cp nuget.config users/
+      - cd users
       - |
         /kaniko/executor \
           --context=. \
@@ -553,7 +563,9 @@ steps:
     commands:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"hub.musk.fun\":{\"username\":\"$HUB_USERNAME\",\"password\":\"$HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
-      - cd flea/users
+      - cd flea
+      - cp nuget.config users/
+      - cd users
       - |
         /kaniko/executor \
           --context=. \

CLAUDE.md

@@ -27,28 +27,39 @@ The services follow a message bus pattern using RabbitMQ for async communication
 **Note:** WTelegram sends both `UpdateNewChannelMessage` and `UpdateEditChannelMessage` for the same message. TelegramListener publishes separate events to avoid duplicate notifications downstream.
 
 Each service follows Clean Architecture with separate projects for:
-- Host (API/entry point)
+- **Host** (API/entry point) - ASP.NET Core application, controllers, startup configuration
-- AppServices (business logic)
+- **AppServices** (business logic) - Use cases, business logic, command/query handlers
-- Core (shared utilities)
+- **Core** (shared utilities) - Domain entities, interfaces, shared logic
-- Api.Contracts (REST API contracts)
+- **Api.Contracts** (REST API contracts) - DTOs, request/response models for REST endpoints (published as NuGet)
-- Async.Api.Contracts (event contracts)
+- **Async.Api.Contracts** (event contracts) - Event DTOs for RabbitMQ messaging (published as NuGet)
-- Persistence (database layer, where applicable)
+- **Persistence** (database layer) - EF Core DbContext, repositories, data access (text-matcher, users only)
-- Migrator (database migrations, where applicable)
+- **Migrator** (database migrations) - EF Core migrations, migration scripts (text-matcher, users only)
+
+**Project Structure Examples:**
+- telegram-listener: Host, AppServices, Core, Async.Api.Contracts (no database)
+- telegram-client: Host, AppServices, Core (no database, no published contracts)
+- text-matcher: Host, AppServices, Core, Api.Contracts, Async.Api.Contracts, Persistence, Migrator
+- users: Host, AppServices, Core, Api.Contracts, Persistence, Migrator
 
 ## Development Commands
 
 ### Running the System
 ```bash
+# IMPORTANT: Before building with Docker Compose, prepare the build environment
+./prepare-build.sh
+
 # Start all services with Docker Compose
 docker-compose up
 
-# Start individual services for development
+# Start individual services for development (no preparation needed)
 cd telegram-client && dotnet run --project src/Nocr.TelegramClient.Host
-cd telegram-listener && dotnet run --project src/Nocr.TelegramListener.Host  
+cd telegram-listener && dotnet run --project src/Nocr.TelegramListener.Host
 cd text-matcher && dotnet run --project src/Nocr.TextMatcher.Host
 cd users && dotnet run --project src/Nocr.Users.Host
 ```
 
+**Note:** The `prepare-build.sh` script copies `nuget.config` to all submodule roots, which is required for Docker builds. This step is automatic in CI/CD but must be run manually for local Docker Compose builds.
+
 ### Building
 ```bash
 # Build individual services
@@ -60,8 +71,17 @@ dotnet build src/Nocr.<ServiceName>.Host
 
 ### Testing
 ```bash
-# Run unit tests (only text-matcher has tests currently)
+# Run all tests in text-matcher
 cd text-matcher && dotnet test
+
+# Run tests for a specific project
+cd text-matcher && dotnet test tests/Nocr.TextMatcher.AppServices.UnitTests/Nocr.TextMatcher.AppServices.UnitTests.csproj
+
+# Run tests with verbose output
+cd text-matcher && dotnet test --verbosity detailed
+
+# Run tests with code coverage (if configured)
+cd text-matcher && dotnet test --collect:"XPlat Code Coverage"
 ```
 
 ### Database Migrations
@@ -75,6 +95,29 @@ cd users && ./src/Nocr.Users.Migrator/AddMigration.sh MyMigrationName
 # Apply migrations (handled automatically by migrator containers in docker-compose)
 ```
 
+### Working with Git Submodules
+
+```bash
+# Initialize submodules after cloning the repository
+git submodule update --init --recursive
+
+# Update all submodules to their latest commits on main
+./update-submodules.sh
+
+# Commit and push changes to all submodules at once
+./commit-all.sh "Your commit message"
+
+# Update a single submodule
+cd telegram-listener
+git pull origin main
+cd ..
+git add telegram-listener
+git commit -m "Update telegram-listener submodule"
+
+# Check status of all submodules
+git submodule status
+```
+
 ## Configuration
 
 **📖 See [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration guide.**
@@ -133,13 +176,47 @@ When running with docker-compose:
 
 ## Key Technologies
 
-- .NET 8
+- **.NET 8** - All services built on .NET 8
-- ASP.NET Core Web APIs
+- **ASP.NET Core Web APIs** - REST endpoints and hosting
-- Entity Framework Core with MariaDB
+- **Entity Framework Core with MariaDB** - ORM for text-matcher and users databases
-- WTelegramClient for Telegram API
+- **WTelegramClient** - MTProto API client for telegram-listener
-- Rebus for message bus (RabbitMQ)
+- **Telegram.Bot** - Bot API client for telegram-client
-- Docker & Docker Compose for containerization
+- **Rebus** - Message bus abstraction over RabbitMQ
-- Drone CI/CD on Kubernetes
+- **RabbitMQ** - Message broker for async event-driven communication
+- **Docker & Docker Compose** - Local development and containerization
+- **Kaniko** - Container image building in CI/CD
+- **Drone CI** - CI/CD pipeline on Kubernetes
+
+## NuGet Package Management
+
+The project uses **Central Package Management (CPM)** with **Package Source Mapping** to manage NuGet dependencies:
+
+### Package Sources
+
+- **nuget.org**: All public packages (Microsoft.*, Serilog.*, etc.)
+- **musk** (private): Internal `Nocr.*` contract packages
+
+### Configuration
+
+The `nuget.config` file in the project root defines package source mapping:
+```xml
+<packageSourceMapping>
+  <packageSource key="musk">
+    <package pattern="Nocr.*" />
+  </packageSource>
+  <packageSource key="nuget.org">
+    <package pattern="*" />
+  </packageSource>
+</packageSourceMapping>
+```
+
+### How It Works
+
+1. **Local Development**: Copy `nuget.config` to each submodule root when needed
+2. **CI/CD**: Drone automatically copies `nuget.config` to `/root/.nuget/NuGet/NuGet.Config`
+3. **Docker Builds**: Kaniko copies `nuget.config` to submodule root before building
+
+This eliminates NuGet warning NU1507 and ensures consistent package resolution across all environments.
 
 ## CI/CD Pipeline
 
@@ -148,39 +225,240 @@ When running with docker-compose:
 The project uses Drone CI with 5 specialized pipelines:
 
 ### 1. Feature Validation (`feature/*`, `fix/*` branches)
-- Triggered on push to feature/fix branches
+**Purpose**: Test feature branches before merging to main
+
+**How to trigger**:
+```bash
+# Create feature branch and push
+git checkout -b feature/my-new-feature
+# ... make changes ...
+git add .
+git commit -m "Add new feature"
+git push origin feature/my-new-feature
+```
+
+**What happens**:
 - Runs build + tests with Testcontainers support
 - Provides fast feedback before merge
 - Duration: ~3-5 minutes
 
 ### 2. Main Validation (`main` branch)
-- Triggered on push to main
+**Purpose**: Ensure main branch stays healthy after merge
+
+**How to trigger**:
+```bash
+# Merge feature to main
+git checkout main
+git merge feature/my-new-feature
+git push origin main
+```
+
+**What happens**:
 - Same checks as feature validation
-- Ensures main branch stays healthy
+- Ensures main branch builds and tests pass
 - Duration: ~3-5 minutes
 
-### 3. Contracts-Only Publish (tags with `contracts_only:`)
+### 3. Contracts-Only Publish
-- Triggered by tag + commit message containing `contracts_only:<service>`
+**Purpose**: Publish NuGet contracts without building Docker images (fast iteration)
-- Publishes NuGet contracts without building Docker images
+
-- Fast iteration on contract changes
+**How to trigger**:
+```bash
+# Update contracts in a submodule
+cd telegram-listener
+# ... update Async.Api.Contracts ...
+git add . && git commit -m "Add MessageEdited event"
+git push
+
+# From parent repo, tag with contracts_only marker
+cd ..
+git add telegram-listener
+git commit -m "contracts_only:telegram_listener - Add MessageEdited event"
+git tag 0.7.41
+git push && git push --tags
+```
+
+**What happens**:
+- Publishes only the specified service's NuGet contracts
+- Skips Docker image builds
 - Duration: ~2 minutes
-- Example: `git commit -m "contracts_only:telegram_listener - Add MessageEdited event"`
 
-### 4. Full Release (clean tags)
+**Services**: `telegram_listener`, `text_matcher`, `users`
-- Triggered by tag without special markers
+
-- Complete release cycle:
+### 4. Full Release
-  1. Publish all NuGet contracts (parallel)
+**Purpose**: Complete release - contracts + images + deployment
-  2. Build all Docker images with Kaniko (parallel, after contracts)
+
-  3. Deploy to Kubernetes (automatic for `v*` tags)
+**How to trigger**:
+```bash
+# Make your changes, commit to main
+git add .
+git commit -m "Implement new feature"
+git push
+
+# Tag for full release (no special markers in commit message)
+git tag v1.3.0
+git push --tags
+```
+
+**What happens**:
+1. Publishes all NuGet contracts (parallel)
+2. Builds all Docker images with Kaniko (parallel, after contracts)
+3. Deploys to Kubernetes (automatic for `v*` tags)
 - Duration: ~8-10 minutes
-- Example: `git tag v1.3.0`
 
-### 5. Deploy-Only (tags with `deploy_only:`)
+### 5. Deploy-Only
-- Triggered by tag + commit message containing `deploy_only:`
+**Purpose**: Deploy existing images without rebuilding (rollbacks, hotfixes)
-- Skips building, only deploys existing images
+
-- Useful for rollbacks and hotfixes
+**How to trigger**:
+```bash
+# Deploy already-built images (e.g., rollback to previous version)
+git commit --allow-empty -m "deploy_only: Rollback to v1.2.9"
+git tag deploy-v1.2.9
+git push && git push --tags
+
+# Or deploy latest images
+git commit --allow-empty -m "deploy_only: Deploy latest"
+git tag deploy-latest
+git push && git push --tags
+```
+
+**What happens**:
+- Skips building entirely
+- Deploys specified tag's images (or `latest`)
 - Duration: ~1 minute
-- Example: `git commit --allow-empty -m "deploy_only: Deploy v1.2.9"`
+
+## Development Workflows
+
+### Making Changes to a Single Service
+
+When working on a specific service (e.g., telegram-listener):
+
+```bash
+# 1. Navigate to the submodule
+cd telegram-listener
+
+# 2. Create a feature branch in the submodule
+git checkout -b feature/new-feature
+
+# 3. Make your changes to the code
+# ... edit files ...
+
+# 4. Test locally (if tests exist)
+dotnet test
+
+# 5. Commit and push in the submodule
+git add .
+git commit -m "Add new feature"
+git push origin feature/new-feature
+
+# 6. Return to parent repo and update submodule reference
+cd ..
+git add telegram-listener
+git commit -m "Update telegram-listener: Add new feature"
+git push origin main
+```
+
+### Updating Contract Packages
+
+When you change event contracts (Async.Api.Contracts) or REST contracts (Api.Contracts):
+
+```bash
+# 1. Make changes to contracts in the submodule
+cd text-matcher
+# ... edit Nocr.TextMatcher.Async.Api.Contracts ...
+git add . && git commit -m "Add new event contract"
+git push origin main
+
+# 2. Return to parent repo and publish contracts only
+cd ..
+git add text-matcher
+git commit -m "contracts_only:text_matcher - Add new event contract"
+git tag 0.8.6
+git push && git push --tags
+
+# 3. Other services can now reference the new contract version
+# Update their .csproj or Directory.Packages.props to use version 0.8.6
+```
+
+### Working Across Multiple Services
+
+When implementing a feature that spans multiple services:
+
+```bash
+# 1. Update each submodule in sequence
+cd telegram-listener
+git checkout -b feature/cross-service-feature
+# ... make changes ...
+git commit -m "Part 1: Update listener"
+git push origin feature/cross-service-feature
+
+cd ../text-matcher
+git checkout -b feature/cross-service-feature
+# ... make changes ...
+git commit -m "Part 2: Update matcher"
+git push origin feature/cross-service-feature
+
+# 2. Update parent repo to reference all changes
+cd ..
+git add telegram-listener text-matcher
+git commit -m "Implement cross-service feature"
+git push origin main
+
+# 3. Tag for full release
+git tag v1.5.0
+git push --tags
+```
+
+## Common CI/CD Workflows
+
+### Test a Feature Branch
+```bash
+git checkout -b feature/add-logging
+# ... make changes ...
+git add . && git commit -m "Add structured logging"
+git push origin feature/add-logging
+# ✅ Drone runs feature-validation pipeline
+```
+
+### Publish Contracts After API Changes
+```bash
+cd text-matcher
+# Update Nocr.TextMatcher.Async.Api.Contracts
+git add . && git commit -m "Add UserDeleted event"
+git push
+
+cd ..
+git add text-matcher
+git commit -m "contracts_only:text_matcher - Add UserDeleted event"
+git tag 0.8.5
+git push && git push --tags
+# ✅ Drone publishes text-matcher contracts to NuGet
+```
+
+### Full Release Workflow
+```bash
+# Work on main branch
+git add .
+git commit -m "Implement payment processing"
+git push
+# ✅ Drone runs main-validation
+
+# Tag for release
+git tag v2.0.0
+git push --tags
+# ✅ Drone runs full-release pipeline:
+#    1. Publishes all contracts
+#    2. Builds all Docker images
+#    3. Deploys to Kubernetes
+```
+
+### Emergency Rollback
+```bash
+# Rollback to last known good version
+git commit --allow-empty -m "deploy_only: Emergency rollback to v1.9.5"
+git tag rollback-v1.9.5
+git push && git push --tags
+# ✅ Drone deploys v1.9.5 images immediately (~1 minute)
+```
 
 ### Deployment Scripts
 
@@ -195,4 +473,83 @@ Located in `_deploy/scripts/`:
 - **Parallel execution** for independent operations
 - **Proper dependency order**: Contracts → Images → Deploy
 - **Kaniko layer caching** for faster Docker builds
-- **Docker-in-Docker** support for Testcontainers in tests
+- **Docker-in-Docker** support for Testcontainers in tests
+
+## Troubleshooting
+
+### Submodule Issues
+
+**Problem:** Submodule directories are empty after cloning
+```bash
+# Solution: Initialize submodules
+git submodule update --init --recursive
+```
+
+**Problem:** Submodule is in detached HEAD state
+```bash
+# Solution: Check out the main branch in the submodule
+cd <submodule-name>
+git checkout main
+git pull origin main
+cd ..
+```
+
+**Problem:** Changes in submodule not reflected in parent repo
+```bash
+# Solution: Update submodule reference in parent
+cd ..  # Return to parent repo
+git add <submodule-name>
+git commit -m "Update <submodule-name> reference"
+```
+
+### Build Issues
+
+**Problem:** NuGet package restore fails with NU1507 warning
+```bash
+# Solution: Copy nuget.config to submodule root
+cp nuget.config telegram-listener/
+cd telegram-listener && dotnet restore
+```
+
+**Problem:** Cannot find Nocr.* contract packages
+```bash
+# Solution: Ensure you have access to the private NuGet feed
+# Check nuget.config has the correct source configuration
+# Verify credentials for the "musk" package source
+```
+
+### Docker Compose Issues
+
+**Problem:** Service cannot connect to RabbitMQ
+```bash
+# Solution: Use the Docker network hostname, not localhost
+# In docker-compose environment: nocr-rabbitmq:5672
+# In local development: localhost:5672
+```
+
+**Problem:** Database connection fails
+```bash
+# Solution: Wait for database health checks to pass
+# Check docker-compose logs for database container
+docker-compose logs nocr-text-matcher-db
+# Database takes 10-30 seconds to be ready on first start
+```
+
+### CI/CD Issues
+
+**Problem:** Pipeline doesn't trigger on tag
+```bash
+# Solution: Ensure tag matches expected patterns
+# Feature validation: feature/*, fix/*, issues/*
+# Main validation: main branch
+# Contracts: Tag with commit message containing "contracts_only:<service>"
+# Full release: Any tag without special markers
+# Deploy-only: Tag with commit message containing "deploy_only:"
+```
+
+**Problem:** Docker image build fails in Kaniko
+```bash
+# Solution: Check if nuget.config is correctly copied
+# Verify _deploy/deploy.sh contains nuget.config copy step
+# Check Drone logs for nuget.config presence in build context
+```

prepare-build.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Prepares the build environment by copying nuget.config to all submodules
+# This is required for both local docker-compose builds and CI/CD
+
+set -e
+
+echo "📦 Copying nuget.config to all submodules..."
+
+for submodule in telegram-client telegram-listener text-matcher users; do
+    if [ -d "$submodule" ]; then
+        cp nuget.config "$submodule/"
+        echo "✓ Copied to $submodule/"
+    fi
+done
+
+echo "✅ Build preparation complete!"

telegram-client

@@ -1 +1 @@
-Subproject commit 9f904d6f0cbcd442adbf19aa778f5910346aa19d
+Subproject commit e8ee01cbe809867305ff02611155cddffccbb401

telegram-listener

@@ -1 +1 @@
-Subproject commit a26dadf978bd0e1d95fca1ae2016a4927501c6da
+Subproject commit 9ad504753550414edd96ef4194a3e0ee7e604e28

text-matcher

@@ -1 +1 @@
-Subproject commit cf9af0e9318c27fc295f16c17853add81491ad37
+Subproject commit 1a55061e4b1b125d1b911f479fc830fb94cd93cc

users

@@ -1 +1 @@
-Subproject commit 370aad3c87aaea62869a97cb981e76b62e906a8a
+Subproject commit 30ae0c043ca2f8958223d6fb343b8b3e3561d727