## Context

Config profiles currently support inline files and inline mounts, but users cannot reference git repositories. This forces users to either copy-paste file contents or use the generic volume mounts system, which doesn't integrate with the git repository model already present in the system.

Git repositories already have clone, branch, and path management. We need to bridge config profiles with git repositories so users can manage dotfiles and configurations in git and mount them into containers via profiles.

## Goals / Non-Goals

**Goals:**
- Allow config profiles to reference git repositories for file mounting
- Support path mapping (source path in repo → target path in container)
- Support branch/tag pinning for reproducible mounts
- Integrate seamlessly with existing profile resolution and instance startup
- Maintain backward compatibility with existing profiles

**Non-Goals:**
- Manual git clone management by users (system handles cloning automatically)
- Writing back to git repos from containers
- Git merge conflict resolution inside profiles
- Submodules support (out of scope for initial implementation)

## Decisions

### 1. Git Mounts as Separate Field (Not Inline in `mounts`)
**Decision**: Add `git_mounts` as a top-level field on `ConfigProfile`, separate from existing `mounts`.
**Rationale**: Existing `mounts` are inline files staged at instance startup. Git mounts are references to external repositories. Keeping them separate maintains clear semantics and allows independent validation.

### 2. Bind Mount at Instance Startup (Not Copy)
**Decision**: Create bind mounts from the repo filesystem path into the container.
**Rationale**: Bind mounts are immediate and don't require copying files. Changes in the repo are reflected in running containers. Alternative (copying files) would require restaging on every instance start and wouldn't reflect live changes.

### 3. Lazy Repo Validation (Not Strict at Save Time)
**Decision**: Validate that the referenced repository exists when the profile is saved, but don't require the repo to be cloned or the branch to exist.
**Rationale**: Repositories may be created after profiles. The instance startup process will handle missing repos gracefully (log warning, skip mount).

### 4. Single Repo per Mount Entry (Not Multiple)
**Decision**: Each `git_mounts` entry references exactly one repository.
**Rationale**: Simplifies the data model and UI. Users can add multiple entries if they need multiple repos.

### 5. Glob Pattern Support in Source Path
**Decision**: Support glob patterns in `source_path` using standard glob syntax (e.g., `configs/**/*`, `*.sh`).
**Rationale**: Users often want to mount categories of files (all config files, all scripts) without listing them individually. The system will expand globs at instance startup and create individual bind mounts for each matched file.

### 6. Auto-Clone on Instance Startup
**Decision**: If a referenced repository is not cloned when an instance starts, the system automatically clones it using the existing clone service.
**Rationale**: Users should not need to manually manage repository state. The system already has clone logic (SSH keys, branch checkout) that can be reused. Clone happens lazily at first use.

### 7. Git Mounts in Profile Preview
**Decision**: Include resolved git mounts in the profile preview output with repository names, paths, and branch information.
**Rationale**: Users need visibility into what will be mounted before starting an instance. This helps debug configuration issues.

## Risks / Trade-offs

**[Risk] Repository clone failure** → **Mitigation**: Clone is attempted at instance startup with full error logging. If clone fails (e.g., bad SSH key, network issue), a clear error is shown and the mount is skipped.

**[Risk] Glob pattern matches too many files** → **Mitigation**: Limit glob expansion to 100 files per mount. Warn if limit exceeded. Users can use more specific patterns.

**[Risk] Branch/tag may not exist** → **Mitigation**: Instance startup attempts checkout after clone. Falls back to default branch with warning.

**[Risk] Performance impact on instance startup** → **Mitigation**: Git mounts are processed in parallel with other startup steps. Clone only happens once per repo. Subsequent instances reuse existing clone.

**[Trade-off] Bind mounts vs inline files** → Bind mounts don't work across filesystem boundaries (repo must be on same host as Docker). This is acceptable for our single-host deployment model.

## Migration Plan

1. Database migration adds `git_mounts` column (nullable JSONB, default empty list)
2. Existing profiles have `git_mounts: []` and continue to work
3. Frontend UI shows new git mounts section only when editing (not required)
4. No changes needed to running instances

## Decisions Resolved

1. **Glob patterns**: YES - Support standard glob syntax in `source_path`
2. **Profile preview**: YES - Include git mounts in preview/resolve output
3. **Auto-clone**: YES - System clones repos automatically, no user reliance