chore: archive 15 completed OpenSpec changes

Move the following audited-and-implemented changes into openspec/changes/archive/2026-06-12-completed-changes-archive/: - backend-frontend-refactoring - config-profile-git-mounts - config-profile-includes-ui - config-profile-multi-repo-mounts - container-monitoring-notifications - git-mount-url-validation - home-path-expansion - mobile-terminal-ux - mount-specificity-ordering - notification-center - persistent-terminal-sessions - session-list-overhaul - ssh-key-mounting - terminal-fullscreen-unified-header - tool-session-progress-and-updates Also regenerated .pi-map*.md files for openspec/changes so the remaining active changes (multi-session-terminal-ux, reorganize-long-files, working-copies, workspace-first-ui) reflect the new layout.
2026-06-12 14:26:55 +00:00
parent 30549f4863
commit caadd59441
493 changed files with 3563 additions and 3490 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-26
@@ -0,0 +1,24 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts (index)
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts
+
+## role
+Archive of completed work for adding git repository mount support to config profiles for version-controlled dotfiles in containers.
+## parent
+index: archive/2026-06-12-completed-changes-archive/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/.pi-map.md
+## children
+- archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs
+  index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.md
+## files
+- .openspec.yaml
+- design.md
+- proposal.md
+- tasks.md
+## links
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,22 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts
+
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/.pi-map.index.md
+
+## role
+Archive of completed work for adding git repository mount support to config profiles for version-controlled dotfiles in containers.
+## files
+- .openspec.yaml | Defines an OpenSpec configuration file with schema type and creation date metadata
+- design.md | Design document for adding git repository mount support to config profiles in a container management system | dep: ConfigProfile, git repositories, clone service, instance startup, Docker/volume mounts, database/JSONB
+- proposal.md | Proposes adding git repository mounts to config profiles for version-controlled dotfiles in containers | dep: config profiles, git repositories, docker/container startup, database migrations, frontend UI/API
+- tasks.md | A completed task checklist for implementing git repository mount functionality across database models, backend API, frontend UI, and documentation | dep: Alembic, SQLAlchemy, Pydantic, FastAPI, TypeScript, Docker Compose, git clone service
+## arch
+Design-driven feature implementation with proposal/design/task phases, covering full stack changes (database models, backend API, frontend UI, documentation) and OpenSpec configuration schema.
+## tags
+design, git, repository, .openspec, adding, mount, config, profiles
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,75 @@
+## 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
@@ -0,0 +1,31 @@
+## Why
+
+Config profiles currently only support inline file content, which is impractical for dotfiles and configuration repositories that users manage with git. Users need a way to include files from git repositories (similar to yadm) so they can version-control their dotfiles and mount them into containers at startup.
+
+## What Changes
+
+- Add `git_mounts` field to config profiles, allowing references to git repositories
+- Mount specific paths from git repositories into containers at configurable target paths
+- Support branch/tag selection for reproducible mounts
+- Integrate with existing profile resolution and instance startup pipeline
+- Update config profile UI to manage git repository mounts alongside existing mounts
+- **No breaking changes** - existing profiles continue to work unchanged
+
+## Capabilities
+
+### New Capabilities
+- `config-profile-git-mounts`: Mounting files from git repositories into containers via config profiles, including repo selection, path mapping, and branch pinning
+
+### Modified Capabilities
+- `tool-instances`: Instance startup pipeline now processes git mounts from resolved profiles before container creation
+- `git-repo`: Repository model may need branch/tag listing for mount configuration
+
+## Impact
+
+- **Backend**: `apps/api/src/models/config_profile.py` - add git_mounts field
+- **Backend**: `apps/api/src/services/config_profile_resolver.py` - resolve git mounts in profile resolution
+- **Backend**: `apps/api/src/services/docker.py` or instance startup - bind mount from repo path to container
+- **Backend**: `apps/api/src/api/config_profiles.py` - CRUD for git mounts
+- **Frontend**: `apps/web/src/pages/config-profiles.tsx` - UI for managing git mounts
+- **Frontend**: `apps/web/src/api/config_profiles.ts` - API types for git mounts
+- **Database**: Migration to add git_mounts column to config_profiles table
@@ -0,0 +1,23 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs (index)
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs
+
+## role
+Contains archived specification documents for a configuration profile feature that manages Git repository mounts, preserved as a historical snapshot from June 12, 2026.
+## parent
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/.pi-map.md
+## children
+- archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts
+  index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts/.pi-map.md
+- archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances
+  index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances/.pi-map.md
+## files
+## links
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,18 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs
+
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.index.md
+
+## role
+Contains archived specification documents for a configuration profile feature that manages Git repository mounts, preserved as a historical snapshot from June 12, 2026.
+## files
+## arch
+Flat directory structure storing archived specification files with no active code, serving as a read-only reference for completed system changes.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts (index)
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts
+
+## role
+Defines requirements for mounting git repositories into containers via configuration profiles, enabling version-controlled configuration and content injection.
+## parent
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.md
+## children
+-
+## files
+- spec.md
+## links
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts
+
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/config-profile-git-mounts/.pi-map.index.md
+
+## role
+Defines requirements for mounting git repositories into containers via configuration profiles, enabling version-controlled configuration and content injection.
+## files
+- spec.md | Defines requirements for adding git repository mounting capabilities to config profiles in a container management system | dep: git, container runtime, config profile system, UI/profile editor
+## arch
+Specification-driven requirements document using structured markdown with sections for overview, requirements, and use cases, serving as a design contract for a container platform feature.
+## tags
+git, spec, defines, requirements, adding, repository, mounting, capabilities
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,149 @@
+## ADDED Requirements
+
+### Requirement: Config profiles can reference git repositories for file mounting
+The system SHALL allow config profiles to include git repository mounts that bind repository paths into containers.
+
+#### Scenario: Create profile with git mount
+- **WHEN** a user creates or updates a config profile with `git_mounts` entries
+- **THEN** the profile stores each git mount with:
+  - `remote_url`: Direct git URL (e.g., "https://github.com/user/repo.git", "git@github.com:user/repo.git")
+  - `source_path`: Path within the repository to mount (e.g., ".", "configs/")
+  - `target_path`: Absolute path inside the container (e.g., "/home/user")
+  - `branch`: Optional branch or tag name (defaults to "main")
+
+#### Scenario: Git mount validation
+- **WHEN** a profile with git mounts is saved
+- **THEN** the system validates that:
+  - `remote_url` is a valid git URL (starts with https://, git@, or ssh://)
+  - `source_path` is a relative path (no leading `/`)
+  - `target_path` can be absolute (starts with `/`) or relative (resolved against working directory, defaulting to `/home/user`)
+  - `target_path` does not contain path traversal sequences (`..`)
+  - No database lookup or repository existence check is performed (validation is deferred to clone time)
+
+#### Scenario: Profile with git mounts is resolved
+- **GIVEN** a config profile with git mounts
+- **WHEN** the profile is resolved for instance startup
+- **THEN** the resolved profile includes the git mounts as configured
+- **AND** repository cloning happens at instance startup time, not at profile resolution
+
+#### Scenario: Git mount is applied at instance startup
+- **GIVEN** a resolved profile with git mounts
+- **WHEN** an instance is started with this profile
+- **THEN** for each git mount:
+  - The repository is cloned from `remote_url` to a temporary location
+  - The source path within the cloned repository exists
+  - A bind mount is created from `clone_path/source_path` to `container:target_path`
+- **AND** if the clone fails or path is missing, a warning is logged and the mount is skipped
+
+### Requirement: Git mounts support glob patterns
+The system SHALL support glob patterns in `source_path` for matching multiple files.
+
+#### Scenario: Mount files matching glob pattern
+- **GIVEN** a git mount with `source_path: "configs/**/*.json"`
+- **WHEN** the instance is started
+- **THEN** the system expands the glob pattern within the repository
+- **AND** creates individual bind mounts for each matched file
+- **AND** preserves directory structure relative to `target_path`
+
+#### Scenario: Glob pattern matches nothing
+- **GIVEN** a git mount with `source_path: "nonexistent/**/*"`
+- **WHEN** the instance is started
+- **THEN** the system logs a warning that no files matched the pattern
+- **AND** the mount is skipped
+
+#### Scenario: Glob pattern limit exceeded
+- **GIVEN** a git mount with `source_path: "**/*"` matching 500 files
+- **WHEN** the instance is started
+- **THEN** the system limits expansion to 100 files
+- **AND** logs a warning: "Glob pattern matched 500 files, limited to 100"
+
+### Requirement: Git mounts trigger automatic cloning
+The system SHALL automatically clone referenced repositories to a persistent storage location on every new container creation. Each instance gets its own fresh clone.
+
+#### Scenario: Repository cloned on container creation
+- **GIVEN** a git mount with a `remote_url`
+- **WHEN** a new container is created with this profile
+- **THEN** the system clones the repository from the URL to an instance-specific directory
+- **AND** the clone proceeds as part of instance startup
+- **AND** instance startup continues once clone completes
+
+#### Scenario: Existing clone updated on new container creation
+- **GIVEN** a repository that was previously cloned for this instance
+- **WHEN** a new container is created with this profile
+- **THEN** the system pulls the latest updates from the remote_url
+- **AND** checks out the specified branch (or default branch if not specified)
+- **AND** uses the updated clone for the bind mount
+
+#### Scenario: Clone failure handling
+- **GIVEN** a git mount referencing a repository with an invalid SSH key
+- **WHEN** the instance attempts to clone
+- **THEN** the clone operation fails
+- **AND** an error is logged with details
+- **AND** the mount is skipped
+- **AND** instance startup continues with remaining mounts
+
+#### Scenario: Per-instance isolation
+- **GIVEN** a git mount referencing a repository
+- **WHEN** multiple instances are created using the same profile
+- **THEN** each instance gets its own independent clone
+- **AND** changes made in one container do not affect other containers
+
+### Requirement: Git mounts support branch pinning
+The system SHALL support pinning git mounts to specific branches or tags.
+
+#### Scenario: Mount specific branch
+- **GIVEN** a git mount with `branch: "develop"`
+- **WHEN** the instance is started
+- **THEN** the system attempts to checkout the "develop" branch in the repository
+- **AND** the bind mount uses the files from the checked-out branch
+
+#### Scenario: Branch fallback to default
+- **GIVEN** a git mount with `branch: "nonexistent"`
+- **WHEN** the instance is started
+- **THEN** the system logs a warning that the branch does not exist
+- **AND** falls back to the repository's current/default branch
+- **AND** the bind mount proceeds with the fallback branch
+
+### Requirement: Git mounts are visible in profile UI
+The system SHALL display git mounts in the config profile editor.
+
+#### Scenario: View git mounts in profile editor
+- **GIVEN** a config profile with git mounts
+- **WHEN** the user views the profile in the UI
+- **THEN** the git mounts section displays each mount with:
+  - Git URL
+  - Source path within repository
+  - Target path in container
+  - Branch/tag (if specified)
+
+#### Scenario: Add git mount via UI
+- **WHEN** a user adds a git mount in the profile editor
+- **THEN** they can:
+  - Enter a git URL directly (https://, git@, or ssh://)
+  - Specify the source path (with autocomplete or validation)
+  - Specify the target path in the container
+  - Optionally enter a branch/tag name
+
+#### Scenario: Remove git mount via UI
+- **WHEN** a user removes a git mount from the profile editor
+- **THEN** the mount is removed from the profile
+- **AND** existing instances using this profile are unaffected
+
+### Requirement: Git mounts are visible in profile preview
+The system SHALL include git mounts in the profile preview/resolve output.
+
+#### Scenario: Preview shows git mount details
+- **GIVEN** a config profile with git mounts
+- **WHEN** the user requests a profile preview
+- **THEN** the preview includes a "git_mounts" section showing:
+  - Repository name and URL
+  - Source path (with expanded glob matches if applicable)
+  - Target path in container
+  - Resolved branch name
+  - Clone status (will clone on container creation)
+
+#### Scenario: Preview warns about missing repository
+- **GIVEN** a config profile with a git mount referencing a non-existent repository
+- **WHEN** the user requests a profile preview
+- **THEN** the preview shows a warning: "Repository [name] not found"
+- **AND** indicates that the mount will be skipped at startup
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances (index)
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances
+
+## role
+Defines requirements for git repository mount processing during tool instance startup.
+## parent
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/.pi-map.md
+## children
+-
+## files
+- spec.md
+## links
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances
+dir: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances
+
+index: archive/2026-06-12-completed-changes-archive/config-profile-git-mounts/specs/tool-instances/.pi-map.index.md
+
+## role
+Defines requirements for git repository mount processing during tool instance startup.
+## files
+- spec.md | Defines requirements for git repository mount processing during tool instance startup, including config profile resolution, bind mount creation, auto-cloning, and failure handling.
+## arch
+Specification-driven requirements document using markdown-based technical specification pattern.
+## tags
+mount, spec, defines, requirements, git, repository, processing, tool
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Instance startup processes git mounts from config profiles
+The system SHALL process git repository mounts from resolved config profiles during instance startup.
+
+#### Scenario: Instance startup with git mounts
+- **GIVEN** a tool instance configured with a profile that has git mounts
+- **WHEN** the instance starts
+- **THEN** the startup pipeline:
+  1. Resolves the config profile (including inherited profiles)
+  2. Collects all git mounts from the resolved profile
+  3. For each git mount, verifies the repository filesystem path exists
+  4. Creates bind mount entries in the compose file for each valid git mount
+  5. Logs warnings for any invalid or missing git mounts without failing startup
+
+#### Scenario: Git mount bind mount creation
+- **GIVEN** a resolved git mount with:
+  - repository filesystem path: `/data/repos/user/project/dotfiles`
+  - source path: `.`
+  - target path: `/home/user`
+- **WHEN** the instance compose file is generated
+- **THEN** a volume entry is added:
+  ```yaml
+  volumes:
+    - /data/repos/user/project/dotfiles:/home/user:ro
+  ```
+- **AND** the mount is read-only by default
+
+#### Scenario: Repository auto-clone on startup
+- **GIVEN** a git mount referencing a repository that has not been cloned
+- **WHEN** the instance starts
+- **THEN** the system triggers a clone operation using the repository's remote URL and SSH key
+- **AND** the system waits for clone completion before proceeding
+- **AND** the bind mount is created from the cloned repository path
+
+#### Scenario: Clone failure handling
+- **GIVEN** a git mount referencing a repository with an invalid SSH key
+- **WHEN** the instance attempts to clone during startup
+- **THEN** the clone operation fails
+- **AND** an error is logged with details
+- **AND** the mount is skipped
+- **AND** instance startup continues with remaining mounts
+- **AND** the instance status is not affected
@@ -0,0 +1,82 @@
+## 1. Database and Models
+
+- [x] 1.1 Create Alembic migration to add `git_mounts` column to `config_profiles` table (JSONB, nullable, default empty list)
+- [x] 1.2 Update `ConfigProfile` SQLAlchemy model to include `git_mounts` field
+- [x] 1.3 Create Pydantic models for GitMount and GitMountCreate schemas with validation
+- [x] 1.4 Add validation for git mount fields (source_path relative or glob, target_path absolute, no path traversal)
+
+## 2. Backend API
+
+- [x] 2.1 Update `POST /config-profiles` endpoint to accept `git_mounts` in request body
+- [x] 2.2 Update `PUT /config-profiles/{id}` endpoint to accept `git_mounts` updates
+- [x] 2.3 Update config profile response schemas to include `git_mounts` in output
+- [x] 2.4 Add validation that referenced repositories exist in the same project
+- [x] 2.5 Update `GET /config-profiles/{id}/preview` to include resolved git mounts
+
+## 3. Profile Resolution
+
+- [x] 3.1 Update `config_profile_resolver.py` to include git mounts in resolved profile output
+- [x] 3.2 Ensure git mounts from included profiles are merged (with override rules)
+- [x] 3.3 Add tests for profile resolution with git mounts
+
+## 4. Instance Startup Integration
+
+- [x] 4.1 Modify instance startup pipeline to process git mounts from resolved profile
+- [x] 4.2 Add helper function to clone repository if not present (reusing existing clone service)
+- [x] 4.3 Add glob pattern expansion for source_path (using standard glob library)
+- [x] 4.4 Add helper function to checkout specified branch after clone
+- [x] 4.5 Generate bind mount entries in compose file for each valid git mount
+- [x] 4.6 Add error logging for missing repos (non-blocking, mount skipped)
+- [x] 4.7 Ensure git mounts are processed in parallel with other startup steps
+
+## 5. Frontend Types and API
+
+- [x] 5.1 Update TypeScript types in `apps/web/src/api/config_profiles.ts` to include GitMount interface
+- [x] 5.2 Update API client functions to include git_mounts in create/update payloads
+- [x] 5.3 Add validation helpers for git mount form fields
+
+## 6. Frontend UI
+
+- [x] 6.1 Add "Git Mounts" section to config profile editor (below existing mounts)
+- [x] 6.2 Create GitMountEditor component with repo selector, source/target path inputs (with glob hint), branch selector
+- [x] 6.3 Add "Add Git Mount" button that opens the editor
+- [x] 6.4 Display existing git mounts with edit/delete actions
+- [x] 6.5 Integrate git mounts into profile save flow (include in form submission)
+- [x] 6.6 Add validation feedback in UI (repo exists, paths valid, branch exists)
+
+## 7. Testing and Verification
+
+- [x] 7.1 Backend unit tests for git mount validation
+- [x] 7.2 Backend integration tests for profile CRUD with git mounts
+- [x] 7.3 Test instance startup with git mounts (verify bind mounts created)
+- [x] 7.4 Test auto-clone behavior (clone triggered, mount created)
+- [x] 7.5 Test clone failure handling (error logged, mount skipped, startup continues)
+- [x] 7.6 Test glob pattern expansion (files matched, limit enforced)
+- [x] 7.7 Test branch checkout behavior (success and fallback)
+- [x] 7.8 Frontend type check passes
+- [x] 7.9 Frontend production build succeeds
+- [x] 7.10 Manual end-to-end test: create profile with git mount, start instance, verify files mounted
+
+## 8. Documentation
+
+- [x] 8.1 Update API documentation with new git_mounts fields
+- [x] 8.2 Add user guide section for using git repositories in config profiles
+- [x] 8.3 Document branch pinning behavior and fallback rules
+
+## 9. External Repository Support
+
+- [x] 9.1 Remove project requirement from git mount validation
+- [x] 9.2 Add endpoint to create external repositories (no project_id)
+- [x] 9.3 Update list_repositories endpoint to return all user repos
+- [x] 9.4 Add endpoint to list external repositories
+- [x] 9.5 Update spec: repos can be external (not tied to project)
+- [x] 9.6 Update spec: auto-clone to persistent location on every container creation
+- [x] 9.7 Update spec: pull updates when creating new containers
+- [x] 9.8 Update spec: per-instance isolation (no shared clones)
+
+## 10. UI Improvements
+
+- [x] 10.1 Add ability to create external repositories from git mount editor
+- [x] 10.2 Show "+ Add new repository..." option in repo dropdown
+- [x] 10.3 Add form fields for repo name and remote URL
+- [x] 10.4 Auto-refresh repo list after creating new repository