# Git Conventions

## Branch Naming

```
<type>/<short-kebab-case-description>
```

- All lowercase, hyphens only — no camelCase or Title-Case
- Keep the description short (3–5 words); the branch name is not the place for detail
- If using a ticket tracker, include the ID: `feature/VAE-123-ai-search`

| Type | Use for |
|---|---|
| `feature/` | New functionality |
| `fix/` | Bug fixes |
| `refactor/` | Code changes with no behavior change |
| `chore/` | Tooling, deps, config, cleanup |
| `docs/` | Documentation only |

**Example:** `feature/ai-search`

---

## Commit Messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <imperative, present-tense summary>

<optional body — explain WHY, not WHAT>
```

- **Type** — same list as branch types above, plus `test`, `style`
- **Scope** — the module/package touched (e.g. `search`, `sync`, `connection`, `vector`, `frontend`)
- **Summary** — imperative mood ("add", not "added" or "adds"); no period at the end
- **Body** — only when the reasoning isn't obvious from the diff (a constraint, a bug workaround, a decision). Skip it for simple/self-explanatory changes.

**Examples:**
```
feat(search): route SearchRequest.aiSearch to AI provider map
fix(sync): prune stale vectors only after full page loop completes
style: reformat
refactor(vector): nest extraData by section for clearer embedding
```

---

## Ticket Titles

Frame as the outcome, not a task log:

```
<Type>: <what changes for the user/system>
```

**Examples:**
- `Feature: Add AI-powered search to Homebox connector`
- `Bug: /api/sync not triggered on login`
- `Chore: Consolidate SearchService provider maps`