# Development Guide

## Project Layout

```text
src/
  Cortex.Api/
    Contracts/
    Data/
    Domain/
    Migrations/
    Options/
    Services/
    Tools/
  Cortex.Web/
    Components/
    wwwroot/
tests/
  Cortex.IntegrationTests/
scripts/
docs/
```

## Important Files

| File | Purpose |
| --- | --- |
| `src/Cortex.Api/Program.cs` | App startup, DI, MCP route, migration/seed modes. |
| `src/Cortex.Api/Tools/CortexTools.cs` | MCP tool surface. |
| `src/Cortex.Api/Services/CortexMemoryService.cs` | Project/item/search behavior. |
| `src/Cortex.Api/Data/CortexDbContext.cs` | EF Core model. |
| `src/Cortex.Web/Components/Pages/Home.razor` | Optional Blazor web UI dashboard. |
| `src/Cortex.Api/Migrations` | Database schema migrations. |
| `docker-compose.yml` | Dev stack. |
| `docker-compose.test.yml` | Test stack. |

## Adding a Tool

1. Add a method to `CortexTools`.
2. Add or update a service method in `CortexMemoryService`.
3. Use `[McpServerTool]` with a stable `Name`.
4. Set `UseStructuredContent = true` when the tool returns structured data.
5. Add an integration test.
6. Update `docs/mcp-tools.md`.

## Adding a Database Change

1. Update domain/entity configuration.
2. Add an EF Core migration.
3. Make sure pgvector-specific SQL remains explicit when needed.
4. Run:

   ```powershell
   .\scripts\test-integration.ps1
   ```

## Changing the Embedding Model

The current model produces 384-dimensional vectors. If the new model has a different dimension, update:

- `Cortex:EmbeddingDimensions`
- migration/schema for `vector(N)`
- indexes
- docs

Changing dimensions for existing data requires either a re-embedding migration or a new embedding table/column strategy.

## Local Docker Config

The scripts keep Docker CLI config inside the workspace where practical:

- `.docker`

This folder is ignored by Git. NuGet uses the normal machine/user configuration.

## Coding Notes

- Keep projects explicit.
- Keep tool names stable.
- Prefer structured tool output.
- Keep Docker ops scriptable.
- Add tests for MCP behavior, not just internal service behavior.