diff --git a/CLAUDE.md b/CLAUDE.md
index 82379c8..4797dc0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,13 +27,19 @@ 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)
-- AppServices (business logic)
-- Core (shared utilities)
-- Api.Contracts (REST API contracts)
-- Async.Api.Contracts (event contracts)
-- Persistence (database layer, where applicable)
-- Migrator (database migrations, where applicable)
+- **Host** (API/entry point) - ASP.NET Core application, controllers, startup configuration
+- **AppServices** (business logic) - Use cases, business logic, command/query handlers
+- **Core** (shared utilities) - Domain entities, interfaces, shared logic
+- **Api.Contracts** (REST API contracts) - DTOs, request/response models for REST endpoints (published as NuGet)
+- **Async.Api.Contracts** (event contracts) - Event DTOs for RabbitMQ messaging (published as NuGet)
+- **Persistence** (database layer) - EF Core DbContext, repositories, data access (text-matcher, users only)
+- **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
 
@@ -60,8 +66,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 +90,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 +171,16 @@ When running with docker-compose:
 
 ## Key Technologies
 
-- .NET 8
-- ASP.NET Core Web APIs
-- Entity Framework Core with MariaDB
-- WTelegramClient for Telegram API
-- Rebus for message bus (RabbitMQ)
-- Docker & Docker Compose for containerization
-- Drone CI/CD on Kubernetes
+- **.NET 8** - All services built on .NET 8
+- **ASP.NET Core Web APIs** - REST endpoints and hosting
+- **Entity Framework Core with MariaDB** - ORM for text-matcher and users databases
+- **WTelegramClient** - MTProto API client for telegram-listener
+- **Telegram.Bot** - Bot API client for telegram-client
+- **Rebus** - Message bus abstraction over RabbitMQ
+- **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
 
@@ -280,6 +321,88 @@ git push && git push --tags
 - Deploys specified tag's images (or `latest`)
 - Duration: ~1 minute
 
+## 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
@@ -345,4 +468,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
\ No newline at end of file
+- **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
+```
\ No newline at end of file