chore: track all project map and index files

Add generated .pi-map.md and .pi-map.index.md files across the repository
so the project navigation maps are shared and versioned. These artifacts
are maintained by project_map_init/patch/validate and must be kept in
sync with source edits.

Note: .cache/ remains ignored (added in previous commit).

apps/api/src/utils/.pi-map.index.md

@@ -0,0 +1,24 @@
+# apps/api/src/utils (index)
+dir: apps/api/src/utils
+
+## role
+Provides Git repository interaction utilities for the API layer, abstracting subprocess-based git operations into reusable Python modules.
+## parent
+index: apps/api/src/.pi-map.index.md
+map: apps/api/src/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- git_control.py
+- git_files.py
+- git_history.py
+- git_url_parser.py
+## links
+index: apps/api/src/utils/.pi-map.index.md
+map: apps/api/src/utils/.pi-map.md
+## workflows
+- change utils behavior
+  read: __init__.py, git_control.py, git_files.py
+## dirty
+-

apps/api/src/utils/.pi-map.md

@@ -0,0 +1,31 @@
+# apps/api/src/utils
+dir: apps/api/src/utils
+
+index: apps/api/src/utils/.pi-map.index.md
+
+## role
+Provides Git repository interaction utilities for the API layer, abstracting subprocess-based git operations into reusable Python modules.
+## files
+- __init__.py | Empty file with no functionality
+- git_control.py | Provides a Python wrapper for common Git repository operations using subprocess calls | exp: class:GitStatus, func:_run_git_command(repo_path: str, *args: str) → str, call:subprocess.run, raise:RuntimeError, func:get_status(repo_path: str) → GitStatus, call:_run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip, call:_run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip, call:GitStatus, call:output.strip().split, call:line.startswith, call:branch_info.split("[ahead ")[1].split, call:int, call:ahead_str.split, call:branch_info.split("[behind ")[1].split, call:behind_str.split, call:len, call:status.untracked.append, call:status.added.append, call:status.deleted.append, call:status.renamed.append, call:status.modified.append, func:create_branch(repo_path: str, name: str, base_branch) → None, call:_run_git_command, call:str(e).lower, func:delete_branch(repo_path: str, name: str, force) → None, call:_run_git_command, func:checkout_branch(repo_path: str, name: str) → None, call:_run_git_command, call:str(e).lower, func:commit_changes(repo_path: str, message: str, author_name: str, author_email: str, files) → str, call:_run_git_command(repo_path, "rev-parse", "HEAD").strip, func:fetch(repo_path: str) → None, call:_run_git_command, func:pull(repo_path: str, branch) → None, call:args.append, call:_run_git_command, func:push(repo_path: str, branch) → None, call:args.extend, call:_run_git_command, func:merge(repo_path: str, source_branch: str, target_branch, message) → str, call:checkout_branch, call:args.extend, call:_run_git_command(repo_path, "rev-parse", "HEAD").strip, func:get_current_branch(repo_path: str) → str, call:_run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip, call:_run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip | dep: subprocess, dataclasses
+- git_files.py | Provides utilities for browsing and manipulating Git repository contents including file trees, branches, file contents, and commits via subprocess git commands. | exp: class:FileTreeEntry, class:BranchInfo, class:FileContent, func:_run_git_command(repo_path: str, *args: str) → str, call:subprocess.run, call:stderr.lower, call:logger.warning, raise:RuntimeError, func:list_tree(repo_path: str, branch, path) → list[FileTreeEntry], call:_run_git_command, call:logger.warning, call:logger.error, call:str(e).lower, call:output.strip().split, call:line.split, call:len, call:meta.split, call:int, call:_get_last_commit_for_path, call:entries.append, call:FileTreeEntry, func:_get_last_commit_for_path(repo_path: str, branch: str, path: str) → dict[str, Any] | None, call:_run_git_command, call:output.strip().split, call:len, func:get_file_content(repo_path: str, branch: str, path: str) → FileContent, call:_run_git_command, call:int, call:size_output.strip, call:_is_binary_file, call:_detect_language, call:_get_last_commit_for_path, call:FileContent, raise:FileNotFoundError, func:_is_binary_file(repo_path: str, branch: str, path: str) → bool, call:subprocess.run, raise:RuntimeError, func:_detect_language(path: str) → str | None, call:Path(path).suffix.lower, call:language_map.get, func:list_branches(repo_path: str) → tuple[list[BranchInfo], str], call:_run_git_command, call:logger.error, call:str, call:r.strip, call:remote_output.strip().split, call:set, call:output.strip().split, call:line.strip, call:branch_name.split, call:branch_name.startswith, call:len, call:any, call:head_output.strip, call:_get_last_commit_for_path, call:branches.append, call:BranchInfo, func:commit_file(repo_path: str, branch: str, path: str, content: str, commit_message: str, author_name: str, author_email: str) → str, call:tempfile.TemporaryDirectory, call:os.path.join, call:os.makedirs, call:os.path.dirname, call:open, call:f.write, call:_run_git_command( worktree_path, "rev-parse", "HEAD", ).strip | dep: logging, subprocess, dataclasses, pathlib, typing, tempfile, os
+- git_history.py | Extracts and structures git commit history, metadata, diffs, and graph visualization data from bare/mirror repositories using subprocess git commands. | exp: class:Commit, class:FileChange, class:CommitDetail, func:_run_git_command(repo_path: str, args: list[str]) → str, call:subprocess.run, raise:RuntimeError, func:get_commit_history(repo_path: str, branch, limit, offset) → dict[str, Any], call:_run_git_command, call:b.strip, call:branches_output.strip().split, call:log_args.append, call:_get_branch_map, call:_get_tag_map, call:log_output.strip().split, call:line.strip, call:line.split, call:len, call:parts[1].split, call:commits.append, call:Commit, call:int, call:branch_map.get, call:tag_map.get, call:count_output.strip, call:_build_graph_data, call:enumerate, call:min, call:commit_dicts.append, call:_commit_to_dict, func:get_commit_detail(repo_path: str, commit_hash: str) → dict[str, Any], call:_run_git_command, call:log_output.strip().split, call:len, call:parts[1].split, call:int, call:_parse_stats, call:_parse_diff, call:_get_branch_map, call:_get_tag_map, call:datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat, call:branch_map.get, call:tag_map.get, call:_file_change_to_dict, raise:ValueError, func:_get_branch_map(repo_path: str) → dict[str, list[str]], call:_run_git_command, call:branch_output.strip().split, call:line.split, call:result[commit_hash].append, func:_get_tag_map(repo_path: str) → dict[str, list[str]], call:_run_git_command, call:tag_output.strip().split, call:line.split, call:result[commit_hash].append, func:_build_graph_data(commits: list[Commit]) → dict[str, Any], call:enumerate, call:hash, call:nodes.append, call:edges.append, func:_parse_stats(stat_output: str) → dict[str, int], call:stat_output.strip().split, call:line.strip, call:line.split, call:part.strip, call:int, call:part.split, func:_parse_diff(diff_output: str) → list[FileChange], call:diff_output.split, call:line.startswith, call:"\n".join, call:files.append, call:FileChange, call:current_diff.append, func:_commit_to_dict(commit: Commit, graph_symbol, graph_depth) → dict[str, Any], call:refs.extend, call:datetime.fromtimestamp(commit.timestamp, tz=timezone.utc).isoformat, func:_file_change_to_dict(file_change: FileChange) → dict[str, Any] | dep: subprocess, dataclasses, datetime, typing
+- git_url_parser.py | Parses various Git hosting service URLs (browser, SSH, HTTPS) to extract normalized base repository clone URLs with .git suffix. | exp: func:extract_base_repo_url(url: str) → str | None, call:url.startswith, call:url.endswith, call:urlparse, call:parsed.netloc.lower, call:parsed.path.split, call:_extract_github_url, call:_extract_gitlab_url, call:_extract_bitbucket_url, call:_extract_generic_url, func:_extract_github_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_gitlab_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_bitbucket_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_generic_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, call:urlparse, func:is_valid_clone_url(url: str) → bool, call:url.startswith, call:urlparse, call:path.endswith, func:parse_git_url(url: str) → dict, call:url.strip, call:urlparse, call:parsed.netloc.lower, call:url.startswith, call:url.split, call:len, call:parts[0].replace, call:is_valid_clone_url, call:extract_base_repo_url | dep: urllib.parse
+## arch
+Utility-layer architecture with functional decomposition into single-responsibility modules (operations, file browsing, history extraction, URL parsing), all relying on subprocess calls to external git binary rather than native git libraries.
+## tags
+call:, git, run, command, get, url, commit, call:len
+## symbols
+- GitStatus
+- FileTreeEntry
+- BranchInfo
+- FileContent
+- Commit
+- FileChange
+- CommitDetail
+- _run_git_command
+## workflows
+- change utils behavior
+  read: __init__.py, git_control.py, git_files.py
+## dirty
+-