> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Action Tools

> Repository file operations and Git version control for data agent-created content. Use the file tool for reads, writes, and server-side copy/move; use git_action for commits, branches, remotes, and pull requests.

## **Overview**

### **Tool group**

```json theme={null}
git_and_file_tools
```

Legacy stored bot toolsets that still name `git_action` as the group are rewritten to `git_and_file_tools` automatically on startup.

### **Tools in this group**

| Tool | Purpose |
| - | - |
| `file` | Read, write, copy, move, and search files in a repository |
| `git_action` | Git version control: commits, branches, remotes, and pull requests |
| `reclaim_duplicate_repos` | Admin-only review of duplicate local clones, or owner/admin review and 14-day quarantine of thread-owned isolated copies |

### **Purpose**

The **git\_and\_file\_tools** group covers repository file operations and Git version control. Use **`file`** for anything that reads or changes file content; use **`git_action`** for version control, not for reading files. The group also includes document text extraction (PDF, Word, PowerPoint, Google Slides, scans via OCR) and Markdown-to-PDF conversion.

See [Cost accounting](https://docs.genesiscomputing.com/docs/Setup/Advanced-Settings.md#cost-accounting) for OCR-request metering.

The **`git_action`** tool provides Git workflows for content your data agents create. It supports branching, diffs, and history, and can auto-register saved files so they are immediately available to other tools and entities across the platform. `repo_id` accepts a local clone id, a remote org/name reference (for example `org/repo`), or a full remote URL; Genesis resolves remote references to the visible local clone when one exists.

> [!NOTE]
>
> In container-based deployments, Genesis prepares the mounted Git workspace on
> startup by ensuring `repos/`, `worktrees/`, and `.genesis_runtime/` exist
> under `GIT_PATH` (default `/app/bot_git`) and by configuring Git trust for
> the shared volume. That keeps `git_action` workflows working on reused
> persistent mounts without manual setup.

When durable Git is enabled in a Databricks App, `git_action` commits and ref
changes are persisted through the configured volume and Lakebase backend. See
[Durable git repositories in the Databricks App pilot](https://docs.genesiscomputing.com/docs/deployments/Databricks/Genesis-On-Databricks.md#durable-git-repositories)
for setup and restore behavior.

[`file` restore behavior](https://docs.genesiscomputing.com/docs/deployments/Databricks/Genesis-On-Databricks#durable-chat-uploads).

In a Databricks App, and wherever Genesis runs as root (Snowflake, EKS and
self-hosted Docker), agent Git refuses repositories whose local or worktree
configuration contains settings outside Genesis's safe allowlist, or that have
submodules. Before each Git operation on an existing repository, Genesis checks
its configuration with up to three read-only Git subprocesses. Git then runs
with hooks and fsmonitor switched off; repository configuration that could run
filters, drivers, helpers, an SSH command, or other commands is rejected rather
than executed. Configuration the operator sets at system or global scope, or in
the server's environment (an SSH command or SSH agent, credential helpers,
`http.*` and `url.*` settings), still applies.
If a check cannot complete, the operation is also refused. Remove unsupported
repository settings or submodules before retrying. Repositories that need Git
LFS or other custom filters, merge or diff drivers cannot be used by agent Git
there: Genesis does not install `git-lfs`, filter configuration in a repository
is refused, and hooks (including LFS's `pre-push`) do not run. This applies to Git Browser,
Blueprint repository operations, and agent workflows that write managed Apps,
skills, dashboards, mission repositories, or Bitbucket checkouts. dbt's
`run_git_command` is unavailable in the App; see
[DBT Cloud Tools](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/Dbt-Cloud-Tools.md#limitations-or-notes).

When a remote Git operation uses credentials from a saved Git connection,
Genesis passes them to the Git process through its environment rather than its
command line or remote URL. Clones keep those credentials out of the remote URL
stored in `.git/config`.

> [!NOTE]
>
> In demo mode (`demo.enabled`), Genesis blocks remote Git and GitHub/GitLab
> actions such as `pull`, `push`, `fetch`, `list_remote_repos`,
> `create_pull_request`, and credential-storage actions. Local repo workflows
> (read, commit, branch, diff) still work. Set `demo.allow_remote_git` to
> `true` on trusted demo instances to lift this block — see
> [Advanced Settings](https://docs.genesiscomputing.com/docs/Setup/Advanced-Settings.md#trusted-demo-relaxation-flags).

### **Key Features & Functions**

**1. File Operations and Diffs**

Read and write repository files, inspect content at arbitrary refs, generate diffs, and apply unified patches.

**2. Commit and Branch Management**

Create branches, switch context, commit changes, and keep work isolated.

**3. History and Status Tracking**

Inspect commit history and working tree status to audit changes.

**4. Save and Register Workflow**

Use a single call to save a file from disk into Git and auto-register and attach it.

**5. PDF Parsing**

Extract text and metadata from PDFs in your repo or by path.

## **Input Parameters for Each Function**

### **`git_action`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Git operation to perform. Common values include: `list_files`, `read_file`, `write_to_file`, `save_file`, `copy_files`, `move_files`, `delete_files`, `generate_diff`, `diff`, `apply_diff`, `show`, `ls_tree`, `commit`, `clone_repo`, `prepare_edit`, `open_edit`, `create_repo`, `set_repo_mode`, `get_history`, `create_branch`, `switch_branch`, `delete_branch`, `get_branch`, `get_status`, `list_repos`, `fetch`, `pull`, `push`, `get_pull_request_info`, `create_pull_request`, `update_pull_request`, `merge_pull_request`, `get_repo_access`, `set_repo_access`, `remove_file`, `force_unlock`, `quarantine_corrupt_objects`. | String |
| **confirm** | For `delete`, retry a deletion refused by the safety check because the file was recently modified or is large. Set to `true` only on the retry requested by that refusal. Default: `false`. | Boolean |
| **draft** | For GitHub `create_pull_request`, open a draft PR. Optional; default: `false`. | Boolean |
| **expected\_body\_sha256** | For GitHub or Bitbucket Cloud `update_pull_request`, expected digest of the current description. Required when sending `body`. | String |
| **dry\_run** | For `merge_pull_request`, read merge readiness without merging or proposing a merge for review. Optional; default: `false`. | Boolean |
| **isolated** | For `clone_repo`, request this thread's own editable copy instead of reusing a clone for shared reading. With a signed-in person, the copy is private to the person who made it, even when the source connection is shared or absent. Optional; default: `false`. When `git_worktrees.enabled` is `true`, use `prepare_edit` instead; `isolated=true` is refused with `USE_PREPARE_EDIT`. | Boolean |
| **repo\_scope** | For `clone_repo`, access scope: `shared`, `personal`, or `restricted`. For `set_repo_access`, changes the source repository's scope. With `git_worktrees.enabled` off, when omitted on clone it follows the connection (`shared` for a shared connection, `personal` for a personal one). | String |
| **repo\_grants** | For `clone_repo` with a stored `restricted` scope, role grants in the form `[{'role_name': 'analyst', 'access': 'view'}]`. `access` is `view` or `edit`; edit includes view. For `set_repo_access`, replaces role grants with `view`, `edit`, or `manage` access (each level includes the preceding level); omit it to keep existing grants. | Array of objects |
| **request\_id** | For `open_edit`, the request ID returned by `prepare_edit` with `status="awaiting_choice"`. Use after the user answers or the default is applied. | String |

Action names are trimmed and matched case-insensitively. For example, `LIST_REPOS`
and `list_repos` both invoke `list_repos`.

**Action-specific fields**

| **Action** | **Required fields** |
| - | - |
| `list_files` | `path` *(optional filter)* |
| `ls_tree` | `ref` *(optional; default: branch currently checked out in the clone — pass `origin/<default_branch>` explicitly to read the default branch)*, `path` *(optional)*, `recursive` *(optional, default: `true`)*, `max_entries` *(optional, default: `10000`)* |
| `read_file` | `file_path` |
| `show` | `file_path`, `ref` *(optional; default: branch currently checked out in the clone — pass `origin/<default_branch>` explicitly to read the default branch)*, `max_chars` *(optional, default: `2000`)* |
| `write_to_file` | `file_path`, `content` |
| `save_file` | `source_path`, `target_path` *(optional)*, `target_filename` *(optional)*, `auto_register` *(optional)*, `auto_attach_entity_type` *(optional when auto\_register is true)*, `auto_attach_entity_id` *(optional when auto\_register is true)* |
| `copy_files` | `source_patterns`, `target_path`, `target_repo_id` *(optional)*, `preserve_structure` *(optional, default: `true`)*, `overwrite` *(optional, default: `false`)*, `exclude_patterns` *(optional)*, `dry_run` *(optional, default: `false`)* |
| `move_files` | `source_patterns`, `target_path`, `target_repo_id` *(optional)*, `preserve_structure` *(optional, default: `true`)*, `exclude_patterns` *(optional)*, `dry_run` *(optional, default: `false`)* |
| `delete_files` | `file_patterns`, `exclude_patterns` *(optional)*, `dry_run` *(optional, default: `false`)* |
| `generate_diff` | `old_content`, `new_content`, `context_lines` *(optional)* |
| `diff` | `from_ref`, `to_ref` *(optional; defaults to the working tree)*, `path` *(optional)*, `unified` *(optional, default: `3`)*, `name_status` *(optional, default: `false`)*, `max_chars` *(optional; patch output default: `200000`)*, `max_entries` *(optional; `name_status=true` default: `10000`)* |
| `apply_diff` | `file_path`, `diff_content` |
| `commit` | `commit_message` *(or `message`)*, `co_authors` *(optional array of `"Name <email>"` strings appended as `Co-authored-by:` trailers)*, `stage_paths` *(optional array of repo-relative paths or globs to stage before committing; default: stage all changes with `git add -A`)*, `dry_run` *(optional, default: `false`)*, `allow_secrets` *(optional array of finding-id strings; default: `null`)* |
| `commit_files_via_api` | `branch_name`, `commit_message`, `files`, `start_branch` *(optional; defaults to the repo default branch when `branch_name` does not exist)*, `author_name` *(optional)*, `author_email` *(optional)*, `expected_branch_head_sha` *(optional)* |
| `clone_repo` | `url`, `isolated` *(optional, default: `false`)*, `shallow` *(optional, default: `true`)*, `single_branch` *(optional, default: `true`)*, `branch_name` *(optional)*, `depth` *(optional; `0` = full history)*, `repo_scope` *(optional)*, `repo_grants` *(optional; restricted scope only)* |
| `prepare_edit` | `repo_id` or remote repository reference, `title` *(short description of the change)*, `branch_name` *(optional; user's requested branch name, used as the fresh-branch default when valid)* |
| `open_edit` | `request_id` returned by `prepare_edit` |
| `create_repo` | `repo_type` *(optional; `storage` by default, or `git` to initialize Git metadata)* |
| `set_repo_mode` | `repo_mode` or `mode` *(optional; `git` upgrades a storage repository, while `storage` is a no-op only when no `.git` entry exists)* |
| `fetch` | `branch_name` *(optional)* |
| `get_history` | `file_path` *(optional)*, `max_count` *(optional)* |
| `create_branch` | `branch_name`, `from_ref` *(optional start point — branch, SHA, or remote ref such as `origin/main`; default: HEAD)*, `reset_if_exists` *(optional; when the branch already exists, reset it to `from_ref` and check it out instead of failing; refused if the working tree has uncommitted changes)* |
| `get_repo_access` | `repo_id` — reads the scope, owner and role grants; requires repository view access. |
| `set_repo_access` | `repo_id`, and one or more of `repo_scope`, `repo_grants`, or `owner_user_id`; changes the source repository's access record, not a working copy. |
| `switch_branch` | `branch_name` |
| `delete_branch` | `branch_name`, `force` *(optional, default: `false`; use `git branch -D` instead of `git branch -d` to delete an unmerged branch)*, `delete_remote` *(optional, default: `false`; also delete the branch on the `origin` remote through the resolved Git connection)* |
| `get_branch` | *(no additional fields)* |
| `get_status` | *(no additional fields)* |
| `list_repos` | `repo_id` *(optional; local repo\_id, remote org/name, or remote URL — performs exact or resolved existence check)*, `pattern` *(optional glob filter)*, `details` *(optional, default: `false`)*, `include_paths` *(optional, default: `false`; requires `details: true`)*, `limit` *(optional page size, maximum `200`)*, `cursor` *(optional; pass the previous response's `pagination.next_cursor` unchanged with the same `pattern`)* |
| `pull` | `branch_name` *(optional; defaults to the current branch)* |
| `push` | `branch_name` *(optional; defaults to the current branch)* |
| `get_pull_request_info` | `pull_request_number`, `include_ci` *(optional; default: `true` — Bitbucket Cloud skips comments, build statuses, and merge checks when `false`; reviews remain)* |
| `create_pull_request` | `branch_name` *(optional; head branch; defaults to current branch)*, `target_branch` *(optional; base branch to merge into; defaults to repo default branch)*, `title` *(string)*, `body` *(optional string)*, `draft` *(optional boolean; default `false`, GitHub only)*, `connection` *(optional)*, `artifact_type` and `artifact_id` *(optional; route a managed-artifact WIP worktree)* |
| `update_pull_request` | `pull_request_number` *(integer)*, `title` *(optional string)* and/or `body` *(optional string)*; `expected_body_sha256` *(string)* is required when `body` is supplied. GitHub and Bitbucket Cloud only. |
| `merge_pull_request` | `pull_request_number`, `dry_run` *(optional; default `false`)*, `strategy` *(optional; Bitbucket Cloud: `merge_commit`, `squash`, or `fast_forward`; omitted uses the destination branch's default)* |
| `remove_file` | `file_path` |
| `force_unlock` | `repo_id` *(required)* |
| `quarantine_corrupt_objects` | `repo_id` *(required)* |

For example, create a restricted clone and grant a role read access:

```python theme={null}
git_action(
    action="clone_repo",
    url="https://github.com/org/repo.git",
    connection="github.team",
    repo_scope="restricted",
    repo_grants=[{"role_name": "analyst", "access": "view"}],
)
```

The result's `scope` is the stored scope and `access` summarizes who can use the
clone. If it includes `access_warning`, pass the warning to the user. For the
Git Browser's access dialog and connection-specific defaults, see [Git Browser](https://docs.genesiscomputing.com/docs/User-Guide/Git-Browser.md#create-or-clone-a-repository).

### Repository access

`get_repo_access` reads the repository's scope, owner and role grants, along with
the last access change and whether the person in the turn may change it. It
requires view access. `set_repo_access` changes the same record as Git Browser's
Manage Access control; it acts on the source repository even when the Git tool
uses working copies.

```python theme={null}
git_action(action="get_repo_access", repo_id="team-notes")

git_action(
    action="set_repo_access",
    repo_id="team-notes",
    repo_scope="restricted",
    repo_grants=[
        {"role_name": "analysts", "access": "view"},
        {"role_name": "engineers", "access": "manage"},
    ],
)
```

A change is authorized for the signed-in person behind the turn, not the agent:
an admin, repository owner, `manage_git` holder (except on another person's
personal repository), or someone with a `manage` role grant on a restricted
repository may change it. Changing ownership to another user requires
`manage_git`. Switching to `shared` or `personal` clears role grants; an
`inherited` repository must be changed at its blueprint or mission. Changes run
under Action Review (`repository.access.v1`): with no tenant rule for this action,
it runs immediately; a pending or denied review does not apply the change. The
response includes `before` and `after` records; if the
result says the write was not confirmed, read the record with `get_repo_access`
before deciding what to do next.

Cost: reading access performs a repository-record read, an audit query and
authorization reads. A change also loads policy, writes the RBAC record and
creates audit rows.

> [!NOTE]
>
> For GitHub PR comments and code reviews, use `github_connector` actions in
> [GitHub Connector Tools](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/GitHub-Connector-Tools.md#pull-request-comments-and-reviews).
> The GitHub-specific `git_action` PR/MR operations continue to support PR and
> MR management on GitHub and GitLab.

> [!TIP]
>
> Prefer `action: save_file` with `auto_register: true` to save to Git and automatically register and attach the file in one step.

> [!NOTE]
>
> `clone_repo` can check out a non-default branch during clone with
> `branch_name`. Unless you override them, `shallow` and `single_branch` both
> default to `true`; set `depth=0` to request full history.

When `clone_repo` reuses an existing clone, Genesis fetches its remote's default
branch before handing it out, unless that clone was successfully fetched within
the last two minutes. A clean, idle clone on that branch is fast-forwarded; a
dirty, busy, or differently branched clone is left in place. The response's
`freshness` explains whether it is current, how many remote commits it may lack,
how many local commits the default branch lacks, or why Genesis could not tell;
`ahead_by` reports the latter count. A checkout with local commits that are not
on the remote is never described as up to date. A failed or timed-out fetch does
not prevent the hand-out and leaves the checkout unchanged. Configure the throttle and timeout
with [`git_clone_reads`](https://docs.genesiscomputing.com/docs/Setup/Advanced-Settings#existing-clone-freshness).

> [!NOTE]
>
> For non-reserved repositories, mode is derived from the repository itself: a
> `.git` entry means the repository is Git-backed, while a repository without
> one is storage-only. Reserved storage-only repository IDs remain storage-only
> even if a `.git` entry exists. `create_repo` defaults to `repo_type="storage"`;
> pass `repo_type="git"` to initialize a Git-backed repository.
> `set_repo_mode(repo_mode="git")` upgrades a storage repository by initializing
> Git metadata. `set_repo_mode` cannot downgrade a Git-backed repository to
> storage-only; `repo_mode="storage"` is accepted only as a no-op when no
> `.git` entry exists. To stop using Git, delete the repository and recreate it
> with `repo_type="storage"`. Newly initialized Git repositories start on
> the `main` branch.

> [!NOTE]
>
> `list_repos` returns the whole visible listing when `limit` and `cursor` are
> omitted. To page the listing, pass a positive integer `limit` (capped at
> `200`), then pass the returned `pagination.next_cursor` as `cursor` with the
> same `pattern`. The `pagination` block reports `page_size`, `returned`,
> `total`, `has_more`, and `next_cursor`. Cursors are signed and bound to the
> requesting user and agent, so do not reuse one across callers or agents. A
> cursor issued before signed cursors were introduced is expired; omit `cursor`
> to start the listing again. Any invalid cursor or limit returns an error
> instead of a partial page.

> [!NOTE]
>
> **Parallel workstreams: reuse to read, branch to edit.** With
> `git_worktrees.enabled` set to `true` (default `false`), a person reads a remote
> repository through their own private copy, created the first time they use that
> remote by a full clone. Other people have their own copies. If a repository is
> busy, Genesis refuses the change after `git_worktrees.lock_wait_seconds`
> (default `30`) rather than waiting longer. For HTTPS GitHub and GitLab downloads,
> `git_worktrees.download_stall_seconds` (default `120`) sets the low-speed timeout;
> see [Git Worktrees configuration](https://docs.genesiscomputing.com/docs/Setup/Configuration-Reference.md#git-worktrees)
> for the HTTPS and SSH behavior. Before the first edit, call
> `git_action(action="prepare_edit", repo_id="org/repo", title="what you are changing")`.
> When the conversation has no branch yet, the first call asks the user in a chat
> card where the edits should go: a fresh branch from the fetched default branch,
> one of the user's existing work branches, or a branch from another remote branch.
> The fresh-branch name is editable. Pass `branch_name` when the user names a
> preferred branch; it becomes the card's suggested name and default when valid.
> If the name cannot be used, Genesis keeps the generated default and returns
> `branch_name_note` with the reason. An existing branch for this conversation is
> kept rather than renamed or duplicated, and an already-answered card keeps its
> selected branch. An unanswered offer waits for
> `git_worktrees.edit_choice_wait_seconds` (default `60`); while
> `git_worktrees.enabled` is on, a sweep runs every `15` seconds and applies the
> default after that wait. If the user sends a message instead of answering, call
> `prepare_edit` again to apply the default. If no chat card can be raised, the
> default starts immediately. After an answer, call
> `git_action(action="open_edit", request_id="...")` with the returned
> request ID. It returns the branch for this conversation. Use the returned `repo_id`
> for edits, commits, and pushes, and the returned plain `branch` name for branch actions.
> In a shared conversation, the answered card resumes the turn as the person it asked,
> not the conversation owner. If Genesis cannot establish who asked for the edit, it
> refuses the write with `EDITING_FOR_SOMEONE_ELSE` rather than applying it to another
> person's branch.
> A shared clone remains read-only: reads, `fetch`, and a fast-forward `pull` of
> its default branch are supported. On the conversation's branch, reads, file
> edits, `create_branch`, `switch_branch`, `commit`, `push`, and `fetch` are
> supported; other actions return `NOT_SUPPORTED_ON_A_BRANCH_YET`. A repository
> without a remote is read-only while this setting is on. A fetch that exceeds
> `git_worktrees.fetch_timeout_seconds` (default `120`, minimum `5`) does not
> start a branch. See [Git Worktrees configuration](https://docs.genesiscomputing.com/docs/Setup/Configuration-Reference.md#git-worktrees).
>
> With the setting off, the existing `clone_repo` flow remains: it reuses a
> visible clone for reading, and `isolated=true` requests this thread's own
> editable copy. If another workstream has a clone in use, Genesis does not hand
> it over; use an isolated copy or read a branch by ref after
> `fetch(branch_name=...)`. Use `fetch_more_history` for older history; do not
> invent a `repo_id` or reclone for history or a branch.

> [!NOTE]
>
> **Auto-switch to default branch on first read.** On the first
> repo-scoped content read in a thread session — `file(action="read"`,
> `"list"`, `"find"`, or `"fast_search")` and `git_action(action="search")`
> or `"grep"` (and `file(action="search")`, which delegates to
> `git_action`) — Genesis may automatically switch a local clone from a
> non-default branch back to the repository default branch when the working
> tree is clean. Successful responses can include `_auto_branch_switch` with
> `auto_switched: true` (`from_branch`, `to_branch`, `message`) or
> `auto_switch_skipped: true` with a `reason`. Auto-switch runs once per
> thread/session/repo key and is skipped when you already called
> `git_action(action="switch_branch")` in the same session, when HEAD is
> detached, when the clone is already on the default branch, when Genesis
> cannot verify status, or when the working tree is dirty. A dirty tree
> includes modified, staged, or conflicted files and **user-owned untracked
> paths**. Genesis internal metadata (`.genesis/`, `.genesis-sync.lock`,
> `.genesis-sync.lock.lock`) remains ignored, except for the user-authored
> `.genesis/dbt-version` runtime declaration. When
> skipped for a dirty tree, `reason` is `dirty_working_directory`. Managed
> remote WIP worktrees are preserved — auto-switch does not run when
> browsing a resolved WIP branch. If a remote repository has no local default
> branch, Genesis creates a local tracking branch from
> `origin/<default-branch>` before switching; if it cannot, it stays on the
> current branch and reports `reason: "default_branch_not_made"`. For a
> repository with no remote, Genesis resolves its default branch from local
> branches: it prefers `main`, then
> `master`, and otherwise uses the branch when exactly one local branch exists.

```python theme={null}
git_action(
    action="clone_repo",
    url="https://github.com/org/repo.git",
    repo_id="myrepo-docs-workstream",
    connection="github.shared",
)
```

> [!NOTE]
>
> For `git_action(action="push")` and `git_action(action="pull")`, omitting
> `branch_name` targets the current branch. Push uses an explicit refspec and
> sets upstream tracking, so a newly created local branch can be pushed or
> pulled without a prior `git push -u`. On a detached HEAD, Genesis returns
> `error_code="git_no_upstream_branch"` and asks you to pass `branch_name`.
> When Git itself reports a missing upstream, the normalized error includes
> `remediation.action="set_branch_name"` with the same guidance.

> [!NOTE]
>
> Every agent commit, merge commit, and file write with a `commit_message`
> names the person who asked for the change in one trailer line, chosen by the
> connection's `git_requester_credit` setting; see
> [Crediting the person who asked](https://docs.genesiscomputing.com/docs/Setup/Connections.md#crediting-the-person-who-asked).
> `git_action(action="commit")` also accepts optional `co_authors`, an array of
> strings such as `["Jane Doe <jane@example.com>"]`. Genesis appends each
> entry as a `Co-authored-by:` trailer, skips duplicates already present in
> the commit message, and drops an entry naming the person already credited.

> [!NOTE]
>
> The primary author for `commit` can come from the repo's configured
> connection or, when none is set, from the caller's scoped default GitHub or
> GitLab connection. On GitHub, GitLab, and Bitbucket connections,
> `git_author_mode` controls that identity. Use `custom` together with
> `git_author_name` and `git_author_email` when you need a fixed verified
> author identity. If no connection author override is resolved, Genesis uses
> the agent's display name and the configured `GIT_USER_EMAIL`; when no email
> is configured, it leaves the address blank rather than inventing one. Commits
> made later through `GitFileManager` re-resolve the author, including the
> noreply address of a GitHub App's bot or of a bot account that owns the
> token; a person's own token leaves the address blank, with a notice.

> [!NOTE]
>
> `git_action(action="commit", dry_run=True)` previews what a commit would
> contain without mutating the repository. Genesis does not run `git fsck`,
> auto-fetch, staging, or the commit itself on this path — it returns a
> read-only preview with `dry_run: true`, path lists such as `already_staged`,
> `would_stage`, `would_commit`, `changed_files`, `untracked_files`, and
> `conflicted_files`, a `diff_summary` object with counts, `can_commit`, and
> `preview_exact`. When check-in transforms or unsupported worktree entry types
> make the preview uncertain, `uncertainty` lists affected paths and a
> `reason`. `commit_message` (or `message`) is still required. Pass
> `stage_paths` to preview selective staging; omit `files` — that parameter is
> only valid for `create_files_bulk`. On failure, responses can include
> `error_code` values such as `GIT_PREVIEW_STATE_CHANGED`,
> `GIT_REPOSITORY_INVALID`, `GIT_STAGE_PATH_INVALID`, or
> `REPO_NOT_INITIALIZED`, and may list `unmatched_stage_paths` or
> `rejected_stage_paths` when staging would fail.

```python theme={null}
git_action(
    action="commit",
    repo_id="customer_analytics",
    commit_message="docs: refresh setup guide",
    dry_run=True,
    stage_paths=["docs/**"],
)
```

> [!NOTE]
>
> Before a real `git_action(action="commit")` (when `dry_run` is false or
> omitted), Genesis validates the local clone with `git fsck`. When damage is
> confined to loose object files that nothing refers
> to — neither committed history nor the staging index — and reachable history
> still walks cleanly, the commit proceeds. The response can include
> `integrity_warnings`, `damaged_object_paths`, and an `integrity_hint` that
> suggests `git_action(action="quarantine_corrupt_objects", repo_id="...")` to
> move the stray objects aside. This applies to local-only repos with no remote
> as well as remotes — a single damaged unneeded object no longer blocks every
> commit. Pack corruption, damage in committed history, damage to a staged blob
> the index still needs, and other fsck failures that are not confined to
> unneeded loose objects still block the commit. Committing while a staged blob
> is unreadable would capture the wrong file contents with no error, so Genesis
> blocks that case. When blocking corruption is detected, Genesis can
> automatically rebuild the checkout from its configured remote and retry the
> commit when all of the following are true: a remote is configured, the
> checkout is not a managed worktree, and there are no unpushed commits on the
> upstream tracking branch. A successful rebuild sets `auto_healed: true` on the
> commit response. When auto-heal is skipped or fails, the response includes
> `error_code: GIT_REPOSITORY_CORRUPTED`, `validation`, `recovery_options`, and
> `auto_heal_attempted` (`no_remote`, `managed_worktree`, `unpushed_commits`,
> or `rebuild_failed`).

> [!NOTE]
>
> `git_action(action="quarantine_corrupt_objects")` moves damaged loose
> objects out of the object store into a timestamped directory under
> `genesis_quarantine/` inside the git directory. Files are moved, not deleted,
> so they remain available for inspection. Genesis only quarantines when
> `git fsck` names specific loose object paths, nothing in the repository
> refers to the damaged objects (not committed history and not the staging
> index), reachable history is intact, and the damage is not in a pack file.
> Successful responses include `message`, `quarantined`, `quarantine_dir`, and
> `repository_valid_after`. When some paths cannot be moved, the response can
> include `skipped` with per-path `reason` values. When a damaged object is
> still referred to, Genesis refuses to move it and returns `error` with
> `needed_object_ids`, `staged_files_for_needed_objects` (object id to staged
> path), and `fsck_output`. If every needed object is staged from a working-tree
> file, `recovery_options` can recommend `restore_object_from_working_tree`:
> delete the damaged object file and stage that file again so git rewrites the
> object with the same id. That repair needs filesystem access agent tools do not
> have today — an operator with a shell can run it. Other failures return
> `error` and may include `fsck_output` or `fsck_output_after` when fsck still
> reports problems after the move.

```python theme={null}
git_action(
    action="quarantine_corrupt_objects",
    repo_id="customer_analytics",
)
```

```python theme={null}
git_action(
    action="commit",
    repo_id="customer_analytics",
    commit_message="docs: refresh setup guide",
    co_authors=["Jane Doe <jane@example.com>"]
)
```

> [!NOTE]
>
> The secret scan for a real commit ignores the exact XML namespace URLs used
> by Talend designs: `http://www.omg.org/XMI`,
> `http://www.w3.org/2001/XMLSchema-instance`,
> `http://www.talend.org/mapper`, and
> `http://www.talend.org/properties`. It also ignores the scheme of HL7
> terminology identifiers on `hl7.org/fhir/ValueSet`,
> `hl7.org/fhir/CodeSystem`, `hl7.org/fhir/NamingSystem`,
> `hl7.org/fhir/sid`, and `terminology.hl7.org/ValueSet`,
> `terminology.hl7.org/CodeSystem`, or `terminology.hl7.org/NamingSystem`
> paths. The identifier host and path remain scanned for potential secrets;
> URLs with a port, credentials, query, fragment, or URI parameters do not
> qualify for this exception. Other content in the staged changes is still
> scanned for potential secrets. The scanner also recognizes URLs with repeated
> JSON-escaped slashes and uppercase `HTTP` or `HTTPS` schemes, so escaping or
> scheme case does not hide a credential or insecure URL. If a real commit is refused with
> `error_code="SECRETS_DETECTED"`, confirm with the user that each finding is
> not a real secret, then pass its `id` in `allow_secrets`, for example
> `allow_secrets=["<finding-id-from-refusal>"]`. The override covers only the
> IDs named; findings added by a later commit are refused again, and `true`
> overrides nothing.

> [!NOTE]
>
> Genesis serializes git index mutations — staging, committing, deleting, and
> similar writes through `git_action` and `file` — per resolved git directory so
> concurrent agent threads in the same server queue instead of racing for
> `index.lock`. Staging runs a subprocess `git add` with an explicit working
> directory instead of GitPython's index add, so concurrent repo operations do
> not temporarily change the process-wide working directory. When another
> process still holds the lock, Genesis retries the mutation up to three times
> with a short backoff and may clear an abandoned lock file that has been
> present for at least 60 seconds. If a lock error still blocks the operation
> after those retries, the response includes `lock_detected: true`, a
> `recovery_action` pointing at
> `git_action(action="force_unlock", repo_id="...")`, and a `recovery_hint`.
> Use `force_unlock` only when you are sure no live git process still owns the
> lock — it removes `index.lock` immediately with no age check. Lock paths
> follow linked worktree `gitdir:` pointers, so managed per-user worktrees are
> covered.

> [!NOTE]
>
> For Bitbucket `pull` calls, Genesis passes `user.name` and `user.email` on
> the Git command automatically. Override those values with `GIT_USER_NAME`
> and `GIT_USER_EMAIL`; when unset, Genesis uses `Genesis Bot` as the name and
> uses the configured `GIT_USER_EMAIL` or leaves the email blank.

> [!WARNING]
>
> Do not use `git_action` or `file` to edit `blueprint_manifest.yaml`. Use
> `create_blueprint(action="CREATE_BLUEPRINT_FROM_THREADS", ...)` for new
> blueprints, `create_blueprint(action="PREVIEW_EDIT", blueprint_name="...",
>     edit_operations=[...])` for targeted deterministic updates, and
> `create_blueprint(action="APPLY_EDIT", preview_id="...")` after review. Use
> `change_description` only when the requested edit cannot be expressed as
> structured operations, and keep blueprint phase definitions in the single
> manifest file instead of splitting them across YAML includes or `$ref`
> patterns.

> [!NOTE]
>
> For `git_action(action="list_repos", details=True)`, each entry in `details`
> includes `mode`, `has_git_dir`, `has_remote`, `scope`, `owner_user_id`,
> `owner_bot_id`, and `undeletable`. When a repo has a remote, Genesis also
> returns a credentials-redacted `remote_url`, and `clone_source` is set when
> the remote host can be inferred as `github`, `gitlab`, `bitbucket`, or
> `azure_devops`. Set `include_paths` to `true` to add `path`. When RBAC hides
> repos from the caller, the response can include `hidden_by_access_count`.
> `mode` reports the repository's effective mode, so a reserved storage-only repository
> can report `mode: "storage"` even when `has_git_dir` is `true`; `has_git_dir`
> reports the physical `.git` entry independently. For remote-clone grouping and
> duplicate fields, see [Output](#output).

> [!NOTE]
>
> For repo-scoped `git_action` calls, `repo_id` accepts the local clone id, a
> remote org/name reference, or a full remote URL. Genesis resolves remote
> references to the visible local clone when one exists. Successful responses
> can include `resolved_from`, `matched_by` (`local_repo_id` or
> `remote_identity`), and `resolved_repo_id`. If no visible clone matches,
> Genesis returns `error_code="REPO_REFERENCE_NOT_FOUND"` with `guidance` to
> inspect clones via `list_repos(details=True)`, clone with `clone_repo`, or
> verify the remote with `check_remote_repo_exists`. When multiple clones match,
> Genesis returns `error_code="REPO_REFERENCE_AMBIGUOUS"` with a `candidates`
> list — retry with an explicit local `repo_id`.

> [!NOTE]
>
> Actions that open or change a local clone check the caller's repository access
> before reading its contents or changing it. A caller without access cannot use
> these actions to discover another user's personal or restricted repository.

> [!NOTE]
>
> The shared `uploads` repository is scoped by conversation access. `git_action`
> and `file` calls can list, search, or read only conversation folders the caller
> may open; operations that reach another conversation's folder are refused.

```python theme={null}
# Exact/resolved existence check; returns the local repo_id when resolved.
git_action(action="list_repos", repo_id="org/repo")
git_action(action="list_repos", repo_id="https://github.com/org/repo.git")
```

### **Remote connection resolution**

When a remote Git workflow omits `connection`, Genesis first uses any saved
connection already associated with that repo remote. If no repo-specific
connection is stored, Genesis falls back to the effective default saved
connection for that platform for the current caller.

Effective defaults follow the same Connections precedence used in the UI and
API: **My default**, then a matching **Role default**. There is no
workspace-wide system default fallback, and Genesis does not treat a sole
visible connection as an implicit default. See
[Default connection layers](https://docs.genesiscomputing.com/docs/Setup/Connections.md#default-connection-layers).

If multiple matching role defaults point at different Git connections and
Genesis cannot choose one, remote actions return
`error_code="AMBIGUOUS_ROLE_DEFAULT_CONNECTION"` together with
`matched_roles` and `matched_role_defaults`. Set a personal default or pass
`connection` explicitly to continue.

When an agent starts a user's new remote download without an explicit
`connection`, Genesis prefers that user's matching personal Git connection: the
user's default when it matches the remote, or their only matching connection.
Genesis uses it only if it can reach the remote. If there are multiple personal
matches without a matching default, the personal connection cannot reach the
remote, or the connection listing/default cannot be read, Genesis falls back to
the team's shared connection when available and tells the user why. Branches
keep the connection pinned to their source download; Genesis does not silently
switch existing branches to a different Git identity.

An editing branch keeps the connection its source download was made through.
If that download has no recorded connection, Genesis carries one forward only
when the remote's shared clones agree on the same shared connection. Naming a
different connection for the branch's remote operation is refused with
`error_code="CONNECTION_IS_PINNED"`; continue with the connection attached to
the branch instead.

`git_action(action="check_stored_credentials")` and the multi-platform
`check_all_stored_credentials` scan resolve the caller's scoped default for
each platform (`github`, `gitlab`, `bitbucket`, `azure_devops`). When role
defaults conflict, those checks return
`error_code="AMBIGUOUS_DEFAULT_CONNECTION"` with an explicit error instead of
reporting "not configured".

For `git_action(action="get_tag_info")`, pass `repo_id` and `tag_name` to read a
tag from an existing local clone. If that tag is absent and the clone has a
remote, Genesis falls back to the provider lookup; include `repo_name` (and
`owner` or `workspace`, as required by the provider) to request a remote lookup
directly. A missing local clone with only `repo_id` returns `NO_LOCAL_CLONE`
rather than creating a clone or calling a provider without a repository name.
When the tag is absent and the local clone has no remote, the response is
`TAG_NOT_FOUND_NO_REMOTE`.

### **Read at a Ref**

Use `show`, `ls_tree`, and `diff` when you need to inspect Git state at a
branch, tag, SHA, or Git expression without switching branches or merging.
`show` displays what a file looks like at a ref, bounded by `max_chars` — it
is not a file-reading mechanism. To read file content with line windows, byte
ranges, or search, use `file(action="read")`. For managed remote artifact
repos where you only need a branch file read, prefer
`file(action="read", branch_name="...")`; use `git_action(action="show")` for
quick ref previews on non-managed remotes and arbitrary refs.

> [!NOTE]
>
> These actions read from the local clone's refs. Run
> `git_action(action="fetch", repo_id="...")` first if you need the remote
> state to be current. `show`, `ls_tree`, and `diff` do not auto-fetch.

#### **Show File Content at a Ref**

```python theme={null}
# Reads the branch currently checked out in the clone when ref is omitted
git_action(
    action="show",
    repo_id="my_project",
    file_path="README.md"
)

# Pass ref explicitly to read the default branch or another ref
git_action(
    action="show",
    repo_id="my_project",
    ref="origin/main",
    file_path="README.md",
)

git_action(
    action="show",
    repo_id="my_project",
    ref="origin/release/2026.05",
    file_path="README.md",
    max_chars=20000
)
```

> [!NOTE]
>
> `show` returns `content` with `encoding="utf-8"` for valid UTF-8 text, or
> `encoding="base64"` plus `binary=true` for binary files and complete files that
> are not valid UTF-8. This preserves invalid or incomplete trailing bytes rather
> than returning lossy text. Successful
> responses also include `resolved_ref`, `branch_name`, `commit_sha`, `sha`,
> `size`, `truncated`, and `max_chars`. `branch_name` is the branch the
> content came from — `null` when the ref is a tag, a SHA, an expression, or
> `HEAD` is detached. Check it before treating the content as canonical: an
> omitted `ref` reads the checked-out branch, which is not necessarily the
> default branch. Content is clipped to `max_chars` (default `2000`); when
> clipped, `truncated=true` and `truncation_notice` explains how to read more.
> For file content with line windows or byte ranges, use `file(action="read")`
> instead of `show`.

#### **List a Tree at a Ref**

```python theme={null}
# Lists the branch currently checked out in the clone, same default as show
git_action(
    action="ls_tree",
    repo_id="my_project",
    path="src",
)

# Or name the ref to list
git_action(
    action="ls_tree",
    repo_id="my_project",
    ref="origin/main",
    path="src",
    recursive=True,
    max_entries=10000
)
```

> [!NOTE]
>
> `ls_tree` returns `entries` with `mode`, `object_type`, `sha`, and `path`.
> `object_type` can be `blob`, `tree`, or `commit` for submodules. Responses
> also include `branch_name` (same meaning as for `show`), plus `truncated`
> and `max_entries`; `truncated=true` means the listing was clipped to
> `max_entries`.

#### **Diff Refs**

```python theme={null}
git_action(
    action="diff",
    repo_id="my_project",
    from_ref="origin/main",
    to_ref="HEAD",
    path="src",
    unified=3
)

git_action(
    action="diff",
    repo_id="my_project",
    from_ref="origin/main",
    name_status=True
)
```

> [!NOTE]
>
> `from_ref` is required for `diff`. For `create_branch`, it is an optional
> start point (default: HEAD). Omit `to_ref` to diff against the working tree.
> With `name_status=true`, Genesis returns `name_status_entries` such as
> `{"status": "M", "path": "src/app.py"}`, and rename or copy rows can also
> include `old_path`. Patch output uses `patch`, supports `max_chars` (default
> `200000`), and sets `truncated=true` when the diff is clipped.

#### **Create Branch**

```python theme={null}
# Create new branch from current HEAD
git_action(
    action="create_branch",
    repo_id="my_project",
    branch_name="feature/new-feature"
)

# Rolling work branch: recreate from latest origin/main every run.
# reset_if_exists uses git checkout -B semantics; refused when the
# working tree has uncommitted changes.
git_action(action="fetch", repo_id="my_project")
git_action(
    action="create_branch",
    repo_id="my_project",
    branch_name="bot/nightly-sync",
    from_ref="origin/main",
    reset_if_exists=True,
)
```

> [!NOTE]
>
> Use `reset_if_exists=True` for bot or flow work branches that are recreated
> from a remote default branch on every run — for example after a prior run
> squash-merged the branch and left the local checkout pointing at stale
> history. Genesis refuses the reset when the working tree has uncommitted
> changes.

#### **Delete Branch**

Delete a local branch after a workstream is complete. By default, Genesis
refuses to delete an unmerged branch; set `force=True` to use Git's force-delete
behavior instead.

```python theme={null}
# Delete a merged local branch
git_action(
    action="delete_branch",
    repo_id="my_project",
    branch_name="feature/old-feature",
)

# Delete an unmerged local branch and its origin branch
git_action(
    action="delete_branch",
    repo_id="my_project",
    branch_name="bot/nightly-sync",
    force=True,
    delete_remote=True,
)
```

> [!WARNING]
>
> `delete_branch` always refuses to delete the checked-out branch or the
> repository's default branch. Set `delete_remote=True` only when the branch
> should also be removed from `origin`; the remote deletion uses the resolved
> Git connection.

### **Azure DevOps Remote Workflows**

Use the existing remote-repository and pull-request actions with
`platform="azure_devops"` or an Azure DevOps `connection`.

| **Action** | **Key fields** | **Notes** |
| - | - | - |
| `list_connections` | `platform="azure_devops"` | Returns saved Azure DevOps connections and their `connection_id` values. |
| `list_orgs` | `platform="azure_devops"`, `connection` | For Azure DevOps, this returns the accessible projects list. |
| `list_remote_repos` | `platform="azure_devops"`, `project` or saved default project | Lists repositories in a project. `org` is accepted as an alias for `project`. |
| `check_remote_repo_exists` | `platform="azure_devops"`, `repo_name`, `project` | Checks whether a repository already exists in the target project. |
| `create_remote_repo` | `platform="azure_devops"`, `repo_name`, `project`, `description`, `private` | Creates a repository in the target project and returns the clone URL details. |
| `configure_remote` | `repo_id`, `remote_url`, `connection` | Stores the Azure DevOps connection on `origin` and normalizes supported Azure DevOps Services clone URLs to canonical HTTPS. |
| `create_pull_request` | `repo_id`, `branch_name`, `target_branch` *(or `base_branch` alias)*, `title`, `body`, `connection` | Creates or reuses an active Azure DevOps pull request. `target_branch` sets the base branch to merge into (defaults to the repo default). Azure DevOps also accepts optional `reviewers` and `work_item_ids`. |

```python theme={null}
git_action(
    action="create_pull_request",
    repo_id="platform_api",
    connection="azure_devops.shared",
    branch_name="feature/native-ado",
    target_branch="main",
    title="Add native Azure DevOps integration",
    body="Adds Azure DevOps Boards, Repos, and Pipelines support.",
    work_item_ids=[5736],
)
```

> [!NOTE]
>
> Azure DevOps remote discovery and PR routing support the canonical
> Azure DevOps Services HTTPS host `dev.azure.com`, the SSH host
> `ssh.dev.azure.com`, and legacy `*.visualstudio.com` clone URLs.

### **Create Pull Request with an Explicit Base Branch**

For `create_pull_request`, `target_branch` sets the branch the pull request
merges **into** (the base or destination branch). It works on GitHub, GitLab,
Bitbucket, and Azure DevOps for regular cloned repos. When omitted, Genesis
uses the repository's default branch. Use it to open a PR against a long-lived
integration branch instead of `main`/`master`, or when automatic default-branch
detection picks the wrong branch.

`base_branch` is an accepted alias for `target_branch`. If both are supplied,
`target_branch` wins. Whitespace-only values are ignored and fall through to
the repo default.

```python theme={null}
git_action(
    action="create_pull_request",
    repo_id="my_project",
    branch_name="fix/my-feature",          # head branch
    target_branch="feature/integration", # base branch to merge into
    title="My PR title"
)
# base_branch is an accepted alias for target_branch:
git_action(
    action="create_pull_request",
    repo_id="my_project",
    branch_name="fix/my-feature",
    base_branch="feature/integration",
    title="My PR title"
)
```

> [!NOTE]
>
> Managed-artifact sources (skills, flows, apps, and agents registered via Remote
> Repositories) currently still target their own default branch when you call
> `create_pull_request`; `target_branch` does not override that behavior on
> those repos.

### **Create a Draft Pull Request or Update an Existing Pull Request (GitHub, Bitbucket Cloud)**

Set `draft=true` on `create_pull_request` to open a GitHub pull request as a draft. It defaults
to `false`; other platforms and managed-artifact worktrees refuse draft creation. GitLab reuses
an open merge request for the same source branch without changing its title or description;
GitHub refuses a duplicate open pull request and identifies its number. Use
`update_pull_request` to change an existing GitHub or Bitbucket Cloud pull request's title or
description. Bitbucket Server and Data Center, GitLab, and Azure DevOps do not support this
update.

```python theme={null}
git_action(
    action="create_pull_request",
    repo_id="my_project",
    title="Review this change",
    draft=True,
)
```

Pass `title`, `body`, or both to `update_pull_request`; an omitted field stays unchanged, while
`body` replaces the whole description. Read the current description first and pass its digest
as `expected_body_sha256` whenever you send `body`. GitHub returns the digest at
`info["data"]["body_sha256"]`; Bitbucket Cloud returns it at `info["body_sha256"]`. If the
description changed after the read, the update is refused so you can reread and apply your edit
to the current text. Title-only updates need no digest. GitHub also permits edits to closed or
merged pull requests; Bitbucket Cloud permits edits to open pull requests only. Updates run
under Action Review. On Bitbucket Cloud, Genesis reads the pull request again before its PUT and
refuses a description that changed since approval; Bitbucket does not provide a conditional PUT,
so an edit made between that final read and write can still be overwritten.

```python theme={null}
info = git_action(
    action="get_pull_request_info",
    repo_id="my_project",
    pull_request_number=42,
    include_ci=False,
)
git_action(
    action="update_pull_request",
    repo_id="my_project",
    pull_request_number=42,
    body="Corrected description",
    expected_body_sha256=info["data"]["body_sha256"],  # Bitbucket Cloud: info["body_sha256"]
)
```

See [GitHub Connector Tools — Output](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/GitHub-Connector-Tools.md#output) for
the metadata and CI error details returned by `get_pull_request_info`.
Reading pull-request information with `get_pull_request_info` and inspecting structured data
with `file(action="inspect_structured_data")` require repository view access, not edit
access. Mutations still require edit access.

### Merge a pull request (GitHub, Bitbucket Cloud)

`merge_pull_request` runs under Action Review because merging cannot be undone. Its preview
uses `dry_run=true` to return the pull request's `get_pull_request_info` without merging or
opening a merge proposal. Review the status, comments, reviews, and merge checks before
requesting the merge.

For Bitbucket Cloud, `strategy` accepts `merge_commit` (or `merge`), `squash`, or
`fast_forward`. Omit it to use the destination branch's configured default; if that branch
has no default, Genesis requests `merge_commit`. The approved proposal names the chosen
strategy and whether Bitbucket will close the source branch. The merge is refused if the
pull request is no longer open, its head changed since approval, or its configured branch
does not allow the strategy. Bitbucket Server and Data Center merges are not supported.
When Bitbucket queues a merge or has not finished it, Genesis does not retry it: the result
remains uncertain until its task or merged state can be checked.

For Bitbucket Cloud, `get_pull_request_info` always returns `reviews` (approvals and change
requests). With `include_ci=true`, it also reads up to three pages each of comments and build
statuses, plus Bitbucket's merge checks; the maximum is eight API reads. It reports
`combined_status`, `ci_summary`, `merge_checks`, `mergeable`, and `merge_conflicts`.
`mergeable` is `null` when Bitbucket cannot evaluate the checks. Set `include_ci=false` to
skip comments, build statuses, and merge checks while retaining reviews.

> [!WARNING]
>
> For repos registered as managed remote sources such as blueprints, apps,
> missions, and agents, Genesis hard-denies direct mutations of the managed base checkout.
> `clone_repo`, `create_repo`, `delete_repo`, `set_repo_mode`,
> `configure_remote`, `pull`, `merge`, `reset`, `revert`, and `commit`
> return `success: false` with `error_code`,
> `managed_repo_guard`, and `next_steps`. The `error_code` value is
> `MANAGED_REMOTE_BASE_CHECKOUT_PROTECTED`.

> [!NOTE]
>
> For managed artifacts, pass `artifact_type` and `artifact_id` on the `file(...)`
> call to select or create that artifact's per-user WIP worktree. Use the same
> pair when opening review with
> `git_action(action="create_pull_request", repo_id="...", title="...",
>     body="...", artifact_type="...", artifact_id="...")`. If a call is
> ambiguous, its response can list up to 10 candidate artifacts or branches;
> retry the same call with one listed type/id pair, or use a listed branch as
> `branch_name`. Candidate details are returned only when repository view access
> is confirmed; otherwise the response gives retry guidance without artifact
> ids, branch names, or paths. For managed agent definitions, set
> `artifact_type="agent"`, `artifact_id="&lt;agent_id&gt;"`, and
> `file_path="agent.yaml"`. You can also use the type-specific workspace
> push tools (`agent_management` `PUSH_TO_REPO`, `app_management`,
> `skill_management`, etc.). **Exception — Git-backed knowledge-base
> (documents) feeds:**
> Genesis owns the managed checkout for KB content; `git_action`, `file`, and
> `connection_api_action` cannot write it. When a blocked mutation hits a
> documents/KB repo, the response includes `managed_document_repo: true` and
> `next_steps` that direct you to `propose_kb_edit` and
> `open_kb_pull_request` in
> [Document Index Tools](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/Document-Index-Tools.md). Those
> tools accept supported KB files (`.md`, `.yml`, `.yaml`, `.json`, `.txt`, or
> `.csv`) under a first-level folder in `documents_root`; the PR tool reports
> its authoritative `changed_files` list. To
> refresh a managed source from origin, use
> `git_action(action="sync_managed_source", repo_id="...", bot_id="...")`.
> To retire it, call
> `git_action(action="unregister_managed_source", repo_id="...")` before
> `git_action(action="delete_repo", repo_id="...")`. To change the stored
> connection or remote URL, re-register the source from the dashboard's
> **Manage Sources** modal on the relevant Skills, Flows, or Apps page instead
> of calling `configure_remote`. For a corrupted checkout or clean re-clone,
> use **Reset Checkout** in that same modal.

> [!NOTE]
>
> A managed artifact push is itself governed by Action Review, including when
> Genesis delivers the approved push through GitLab's Commits API fallback
> after a raw Git push is rejected. A pending review means the branch was not
> pushed and no pull request was opened; wait for the person's decision
> instead of retrying. A denied push remains unwritten. GitLab's Commits API
> setting changes only delivery of that already-approved push, not whether the
> push requires review.

> [!NOTE]
>
> **Managed checkouts with no git remote.** A managed source's on-disk checkout
> can exist without a configured git remote (`has_remote=false` on
> `list_repos(details=true)`). Genesis cannot verify freshness against origin or
> maintain a fresh mirror in that case, but the working tree remains readable
> and editable. Use `file()` to edit files on the default branch, then commit
> only those files with
> `git_action(action="commit", repo_id="...", stage_paths=[...], commit_message="...")`.
> `stage_paths` is required for these shared base checkouts and must contain
> exact repo-relative file paths, not directories or globs. A commit is refused
> if the checkout is detached or not on its resolvable default branch; branch
> switching and pull requests are unavailable for a source with no remote.
> Sync is refused while user changes remain, so commit those changes before
> syncing. For a local managed source, syncing with `release_ref="latest"`
> resolves to the default branch rather than a release tag.
> Default reads on the managed base checkout — `file(action="read")` with no
> `branch_name`, `file(action="list")`, `file(action="fast_search")`, and
> related `git_action` file reads — serve content from the local checkout and
> attach `freshness_notice`: "This managed repository has no git remote
> configured, so freshness could not be verified against the remote source.
> Content was read from the local checkout and may be stale." Pass an explicit
> `branch_name` when origin-backed reads are available, or re-register the
> managed source with a remote URL and connection when you need verified
> freshness and remote pull requests.

> [!NOTE]
>
> **Managed checkout exclusions (`checkout_exclude`).** Operators can configure
> an ordered `checkout_exclude` pattern list on a managed source (via
> **Config → Managed Sources** or `POST` / `PATCH` `/api/managed-sources`) to
> prune paths from the managed **base** checkout with Git sparse checkout.
> This is independent of `include` / `exclude`, which govern which artifacts
> Genesis discovers and enables and retire previously synced skills, flows, or
> apps that no longer match on the next sync. After sync, pruned paths are not on
> disk, so `git_action(action="list_files")`, `file(action="list")`, and the
> Git Browser tree for that `repo_id` will not show them. To read a pruned
> path from the remote without changing the checkout policy, use
> `git_action(action="show", ref="origin/&lt;branch&gt;", ...)` after
> `git_action(action="fetch")`. Per-user managed worktrees used for WIP edits
> (skills, flows, apps, agents) remain full checkouts even when the base
> checkout is sparse. Clearing `checkout_exclude` to `[]` and syncing restores
> a full base checkout on the next successful sync.

> [!NOTE]
>
> On managed GitLab repos, `git_action(action="commit_files_via_api")` can
> land a prepared diff through the GitLab Commits API. When the action uses a
> stored GitLab connection, it runs under Action Review like other remote
> writes. A `pending_review` result means nothing was committed; a review card
> is posted in the current thread, and you should not call the action again
> while it waits. The approval covers the canonical project path, branch,
> commit message, exact file contents, and the branch base. If a file or the
> branch changes before approval, propose the action again with the current
> values. A `reconciliation_required` result may or may not have committed,
> so do not retry it.
>
> If the install has no saved GitLab connection and its GitLab credential
> comes only from the `GITLAB_TOKEN` (or `GITLAB_PRIVATE_TOKEN`) environment
> variable, a commit no rule could cover runs directly, as before; a rule on
> another git action (only merge request notes, say) does not count. One a rule
> could cover goes to that rule with this deployment's GitLab credential, the
> same one `gitlab_api_request` uses there, for every GitLab request it makes,
> the default-branch lookup when no `start_branch` is given included: the rule allows it, holds it for a
> person, or denies it, and the review card says it runs with this
> deployment's GitLab credential, not a person's. No person's credential is
> ever used for it, and it is never sent if the GitLab it was approved for
> moves, if a saved connection is added, or if the requester can no longer use
> `git_action`. With an environment token beside saved connections that the
> call does not name, a policy that would hold or deny the commit still
> refuses it. A project that GitLab cannot resolve is refused.

```python theme={null}
git_action(
    action="list_repos",
    details=True,
    include_paths=True
)
```

### **`file`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | File operation. Values: `read`, `read_multiple`, `write`, `write_multiple`, `delete`, `list`, `find`, `search`, `fast_search`, `search_replace`, `search_replace_bulk`, `edit`, `copy`, `move`, `delete_files`, `unzip`, `create_archive`, `inspect_structured_data`, `append`, `insert`, `patch`, `RTFM`. | String |
| **file\_path** | Repo-relative file path. | String |
| **repo\_id** | Repo id. Required for `read_multiple`; optional for other actions that can default to uploads. | String |
| **artifact\_type** | Managed artifact type for WIP-worktree routing. Pair with `artifact_id` to select an artifact when a managed repo contains multiple artifacts: `app`, `blueprint`, `mission`, `document`, `skill`, `flow`, or `agent`. | String |
| **artifact\_id** | Managed artifact id for WIP-worktree routing. Pair with `artifact_type` when a managed repo contains multiple artifacts (for example, the stable `agent_id` for `artifact_type="agent"`). `app_id` is an accepted alias when targeting app worktrees. | String |
| **branch\_name** | Explicit branch for a file read or managed-repository worktree. On a managed GitHub base checkout, omission selects the default branch from origin. Elsewhere, a branch different from the checked-out one is fetched and read from origin. Without a remote, Genesis reads the local tree and may include `freshness_notice` or `branch_note`. | String |
| **content** | File content. For text, pass the text directly. For binary (zip, image, parquet, sqlite, etc.), pass the base64 string here and set `is_base64=true` so it is decoded before writing. | String |
| **is\_base64** | For `action="write"`: when `true`, `content` is base64-decoded to the original bytes before writing (use this for binary files). For `action="write_multiple"`: ignored at the top level — set `is_base64` inside each `files[]` item instead. Ignored by all other actions. Default: `false`. | Boolean |
| **files** | Bulk files array. For `write` and `write_multiple`: `[{path, content, is_base64}]` (`content` is required). For `read_multiple`: path strings like `["a.sql"]` or objects like `[{"path": "a.sql", "start_line": 1, "max_lines": 40}]` — each entry can carry its own line window. `repo_id` is required for `read_multiple`. | Array |
| **pattern** | Search text or regex for `search`; a glob matching file paths for `list` and `find`. `search` checks file contents, not names. To find a file by name, use `find` with a glob such as `*name*`. | String |
| **max\_results** | Maximum results for `search` or `inspect_structured_data`. For `search`, defaults to `100` matching-line records and accepts `1`–`1000`; for `inspect_structured_data`, defaults to `10`. | Integer |
| **source\_patterns** | Glob patterns for `copy` and `move`, or exact file paths for bulk operations. | Array of Strings |
| **target\_path** | Destination directory for `copy` and `move`. | String |
| **preserve\_structure** | For `copy` and `move`, preserve nested paths under the matched pattern scope. Default: `true`. | Boolean |
| **overwrite** | For `copy`, overwrite an existing target file. Default: `false`. | Boolean |
| **dry\_run** | For `copy`, plan matching file transfers without creating directories or copying files. Default: `false`. Managed-remote repository copy previews are refused because routing can create or refresh a worktree. | Boolean |
| **include\_sha256** | For `read` and `read_multiple`: include `content_sha256` and `content_size_bytes` for the complete file. Genesis reads the full file to compute the hash. Default: `false`. Use for integrity preflight before apply or sync. | Boolean |
| **return\_verbose\_edit\_result** | For `search_replace` and `edit`: return the full before/after preview in addition to counts and changed line numbers. Default: `false`. The edit is already applied; set this only when you need the surrounding context of what changed. `dry_run` always includes previews. | Boolean |

> [!NOTE]
>
> Repository file operations cannot read or change the `.git` metadata directory,
> including when a symlink points into it. Directory copies and archives omit Git
> metadata. For `file(action="unzip")`, a destination inside `.git` is refused;
> archive entries aimed there are skipped and listed in `refused_files`.

> [!NOTE]
>
> Bulk writes validate the `files` payload before writing. For
> `action="write_multiple"`, `files` is required, must be a non-empty array,
> and every entry must be an object. For `action="write"` when a non-empty
> `files` value requests a bulk write, the same array-of-objects validation
> applies. If `files` is a
> JSON string, it must contain valid JSON that decodes to an array; otherwise
> the request fails without writing any files. Invalid entries identify their
> zero-based index in the error.

> [!NOTE]
>
> For `file(action="search_replace")` and `file(action="edit")`, successful
> applied edits return a compact result by default: `replacements_made` or
> `edits_applied`, `changed_line_count`, and up to `20` `changed_lines` (with
> `changed_lines_truncated: true` when more lines changed). Genesis omits the
> large `preview` (and, for `edit`, the per-edit `changes` array) unless you
> pass `return_verbose_edit_result=true` or use `dry_run=true` to preview
> without writing.

> [!TIP]
>
> If `repo_id` is omitted for `action="write"`, file paths are saved under `uploads/&lt;thread_id&gt;/...` with a fallback to `uploads/misc/...`. Successful writes also echo the resolved `file_path` and `thread_scope` so follow-on tools can reference the actual saved location. For `action="read_multiple"`, `repo_id` is required.

#### File-write placeholder guidance

> [!NOTE]
>
> File writes refuse content that is a clipped-history preview or a compressed
> argument/result placeholder rather than the original text. This applies to
> `content`, bulk file content, and text replacements. The response uses
> `error_code="content_clipped_from_history"` and confirms that nothing was
> written. If an earlier call already wrote the file, read it back instead; to
> change it, send the complete text. When the response includes an
> `archive_ref`, retrieve the original argument with
> `manage_thread_memory(action="GET_COMPRESSED_PARAM_ARCHIVE", archive_ref=...)`.
> GenesisApps `WRITE_FILE` and `WRITE_FILES` apply the same guard.

> [!NOTE]
>
> **Transferring a file that already exists.** Never read a file and write the
> same bytes back. When the source already lives in a repository Genesis can
> reach, transfer it server-side with `file(action="copy")` or
> `file(action="move")` — byte-exact, including binaries (zip, image,
> parquet), with no content in the arguments and nothing to truncate:
>
> ```
> file(action="copy", repo_id="src", source_patterns=["big.sql"], target_path="old/big.sql")
> file(action="copy", repo_id="src", target_repo_id="dst", source_patterns=["fixture.zip"], target_path="fixtures")
> file(action="move", repo_id="src", source_patterns=["fixture.zip"], target_path="archive/fixture.zip")
> ```
>
> For a single source, `target_path` is the new filename; for multiple sources
> or cross-repo copies, it is the destination directory. Add `target_repo_id`
> to copy or move into another repo. Inline `content` on `action="write"` is
> for text you are authoring — never for bytes you just read.

> [!NOTE]
>
> **Binary bytes not already on disk.** For content the bot generated or
> supplied inline (not an existing repo path), write base64 with
> `is_base64=true` so it is decoded rather than stored as literal ASCII:
>
> ```
> file(action="write", file_path="fixture.zip", repo_id="dst", content="<base64>", is_base64=true)
> ```
>
> Without `is_base64=true`, the base64 string is written as literal ASCII text
> and the resulting file is corrupt. If `is_base64=true` is passed with content
> that is not valid base64, the tool returns a structured error instead of
> writing a bad file. For multi-file writes, set `is_base64` inside each
> `files[]` item rather than at the top level.
>
> On unpaged reads, `return_base64=true` returns a size-limited byte range by
> default (`truncated=true` with a `continuation` hint), not the full file. It
> does not bypass structured-file refusal on the text path — a clipped JSON/XML
> prefix will not parse. Page with `start_byte`/`max_bytes` or read the whole
> file before decoding.

> [!NOTE]
>
> `file(action="read")` supports partial and targeted reads with `start_line`,
> `max_lines`, `start_byte`, `max_bytes`, `end_byte`, `tail_bytes`,
> `max_chars` (alias for `max_bytes`), `search_pattern`, `context_lines_before`,
> `context_lines_after`, `max_matches`, `return_line_numbers`, `encoding`,
> `force_text`, `return_base64`, and `include_sha256`. `start_line` is
> 1-based; a negative value counts back from the end of the file (for example,
> `start_line=-20` with `max_lines=20` reads the last 20 lines). `max_lines`
> defaults to `100`. For files above \~10 KB, use `action="search"` first, then
> read only the window you need. `file(action="read_multiple")` accepts the
> same per-entry windows in `files` (for example
> `[{path, start_line, max_lines}]`); identical path-and-window entries are
> deduplicated, but you can request both the head and tail of one file as
> separate entries. When the target is a managed GitHub repo base checkout,
> Genesis reads remote truth instead of the shared local clone when the checkout
> has a git remote. Pass `branch_name` to read that ref on origin; omit it to
> read the managed default branch. When the checkout has no git remote, Genesis
> reads the local tree instead and includes `freshness_notice` (see the managed
> no-remote note above). For other checkouts, when `branch_name` names a branch
> other than the checked-out one, Genesis fetches and reads `origin/<branch>`;
> if the fetch fails, it reads the last-fetched ref with a warning when one
> exists, or returns an error if there is no ref to read. If that local branch
> has commits that are not on origin, Genesis reads the local branch and says
> so. On the origin-backed remote-read path, `start_line`,
> `max_lines`, and
> `return_base64` are supported, but `search_pattern`, `context_lines_before`,
> `context_lines_after`, `max_matches`, `start_byte`, `end_byte`, `max_bytes`,
> `tail_bytes`, `max_chars`, `return_line_numbers`, `force_text`, and
> `encoding` return an explicit error. Binary content on the remote-read path
> must use `return_base64=true`.

For repository file reads, listings, and searches, Genesis also says when it
cannot prove that a clone is the caller's own and matches its default branch.
The response includes `copy_note` or `copy_notes`, explaining that the copy may
contain commits or uncommitted changes not on that branch, or could not be
compared. When part of the comparison is unreadable, the note still reports what
is known: for example, a known commit count is preserved when working-tree status
cannot be read, and an unreadable fetch record says the remote branch may be
behind. Genesis keeps reading that checkout as it is; it never substitutes the
remote's files. To inspect the remote default branch instead, fetch it and
use `git_action(action="show", repo_id="...", ref="origin/<default-branch>",
file_path="...")` or `git_action(action="ls_tree", repo_id="...",
ref="origin/<default-branch>")`. Those actions include `remote_ref_note` when an
`origin/<branch>` result may be stale because the clone has no successful fetch
on record or its latest fetch failed.

> [!NOTE]
>
> For large reads, check `truncated`, `size_capped`, and `total_size` before
> parsing `content` or assuming the full file was returned. `max_bytes` (or the
> older alias `max_chars`) caps how many **bytes** of content a read returns;
> the window still stops on a whole-line boundary once those bytes are spent
> and sets `size_capped`. Requests above the tool-output file-read budget
> (default `65,536` bytes / 64 KB) are clamped to it. Pass a value larger
> than the file size to read it whole. When an unpaged read would clip
> structured single-document files (`.json`, `.geojson`, `.xml`, `.yaml`, `.yml`,
> or extensionless files whose content starts like JSON or XML), Genesis refuses
> with `success: false` and omits `content` rather than returning unparseable
> partial JSON/XML/YAML. Detection uses the file extension when it discloses the
> type, and content sniffing when the extension does not. The error includes
> `total_size`, `truncated: true`, and a short `content_preview`; page with
> `start_byte`/`max_bytes` or `start_line`/`max_lines`, raise `max_bytes` to
> read the file whole, or use `file(action="inspect_structured_data")` for
> JSON/XML. Line-oriented `.jsonl`/`.ndjson` files can still return partial
> content.

```python theme={null}
file(
    action="read",
    repo_id="customer_analytics",
    file_path="docs/churn_methodology.md",
    branch_name="feature/churn-analysis",
    start_line=1,
    max_lines=40
)

# Read the last 50 lines of a large log file
file(
    action="read",
    repo_id="customer_analytics",
    file_path="logs/app.log",
    start_line=-50,
    max_lines=50
)
```

> [!NOTE]
>
> Successful remote reads can also include `branch_name`, `sha`,
> `_remote_read`, and `_remote_read_window` when Genesis applies a line window
> client-side. When Genesis reads the local checkout because the managed source
> has no git remote, responses include `freshness_notice` and may set
> `source` to `local_tree` instead of origin metadata. When `return_base64=true`, the response includes
> `encoding="base64"` and, for unpaged reads that exceed the byte limit,
> `truncated=true` with a byte-range `continuation`. Clipped base64 payloads
> that look like JSON or XML may also include `structured_partial_warning`.
> When `include_sha256=true`, the response includes `content_sha256` and
> `content_size_bytes` for the complete file (hashing reads the full file even
> when you also pass line or byte windows).

> [!NOTE]
>
> `file(action="read")` sizes its own result to fit the file-read inline budget
> (default `65,536` bytes / 64 KB, configurable via
> `tools.output_governor.file_read_budget_bytes` or
> `GENESIS_TOOL_OUTPUT_FILE_READ_BUDGET`) and always returns inline `content`
> — never a spill reference. When more remains, responses include `truncated`
> and/or `size_capped`; continue from the reported `end_line` with another
> windowed read. A single line longer than the budget is the exception: it
> returns cut mid-line with `partial_line` set, and only `start_byte` /
> `max_bytes` can reach the remainder. When `git_action(action="read_file")` or
> `file(action="inspect_structured_data")` still exceeds the governor cap,
> Genesis returns `tool_output_capped`, `preview`, `truncation_info`,
> `full_output_ref`, and `agent_guidance` instead of the full inline payload.
> When `full_output_ref` is not `null`, the full text is saved under
> `truncated_tool_outputs/&lt;thread_id&gt;/...` in the `apps` BotGit repo.
> Re-reading that spill path uses the default inline budget (not the relaxed
> file-read budget), so page it back with
> `file(action="read", file_path=full_output_ref, repo_id="apps", start_byte=0, max_bytes=N)`,
> continuing from each response's `continuation.next_start_byte`. Use the byte
> range rather than a line window: only the byte range returns the saved copy
> exactly as it was written — the whole-file and line-window paths read the file
> in text mode, so a `\r\n` in the spilled output comes back as `\n`.

> [!WARNING]
>
> A single-file `file` action (`write`, `edit`, `search_replace`, `append`,
> `insert`, `patch`, or `delete`) whose `repo_id="apps"` path names a registered
> GenesisApp workspace is routed to that app's workspace, as if you had passed
> its `app_id` as `repo_id`. This applies only when the path identifies that
> app's workspace and the call has no second target. Bulk, pattern, copy, and
> move forms are not rerouted; use the app id as `repo_id` for those operations
> or use `apps_action`.

> [!NOTE]
>
> To update a GenesisApp safely, prefer
> `apps_action(action="WRITE_FILE", app_id="sales-dashboard", path="app.py", content="...")`
> or `apps_action(action="WRITE_FILES", ...)`. The generic `file` tool can use
> the app id as `repo_id`, for example
> `file(action="write", repo_id="sales-dashboard", file_path="app.py", content="...")`.
> This is also the recommended form for bulk operations. Blocked responses include `error`, `next_steps`,
> `blocked_by: "microapp_apps_repo_mutation_guard"`, `app_id`, `rel_path`, and
> `matched_param`.

### **`file(action="create_archive")`**

Create a ZIP archive from an entire repository or a repo-relative file or
folder. Genesis writes the generated ZIP under `.archives/` in the repository
and returns archive metadata such as `archive_path`, `download_link`,
`file_count`, `total_size`, `archive_size`, `output_filename`, and `repo_id`.

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **repo\_id** | Repository identifier to archive. | String |
| **path** | Optional repo-relative file or folder to archive. Omit this field to archive the entire repository. | String |
| **output\_filename** | Optional ZIP filename. When omitted, Genesis uses the repo id plus a timestamp and appends `.zip`. | String |
| **exclude\_patterns** | Optional additional gitignore-style patterns to exclude from the archive. | Array of Strings |
| **include\_git** | Optional, default: `false`. Must remain `false`; `true` is refused because archives never include `.git/`, whose config can hold credentialed remote URLs. | Boolean |

```python theme={null}
file(
    action="create_archive",
    repo_id="my_repo",
    path="docs/",
    output_filename="docs_bundle.zip",
    exclude_patterns=["**/*.tmp"],
)
```

> [!NOTE]
>
> `file(action="create_archive")` excludes housekeeping paths by default:
> `.archives/`, Python caches (`__pycache__`, `*.pyc`, `*.pyo`, `*.pyd`), OS
> artifacts (`.DS_Store`, `Thumbs.db`), `node_modules/`, virtual environments
> (`.venv/`, `venv/`), `.env` and `.env.*`, and microapp runtime scratch
> directories (`.microapp_home/`, `.microapp_state/`, `.microapp_venv/`). Git
> metadata is always excluded; `include_git=true` returns an error. Clone or push
> the repository to share its history.

### **`ocr`**

Extract text from scanned PDFs and image files in a Git repository with the
`ocr` tool. Set `filepath` to a repository-relative file path and provide its
`repo_id`. `method` defaults to `"auto"` and tries Databricks, Snowflake,
Tesseract, then the OCR engine built into macOS or Windows; for image files it
can then use the chat model's vision. Use `"on_device"` to select the local OS
engine directly (Windows needs an OCR language installed; Linux has no on-device
engine), or `"databricks"` to select Databricks `ai_parse_document` directly.
The on-device and vision routes accept HEIC/HEIF images, including photos from
iPhone; `method="vision"` remains limited to image files.

For a PDF attached to the current chat, use the `uploads` repository, pass the
upload-relative path as `filepath`, and set `method="databricks"`. Genesis reads
the file from that thread's upload folder and sends it to Databricks for parsing:

```python theme={null}
ocr(filepath="<upload-relative-path>", repo_id="uploads", method="databricks")
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `filepath` | string | required | Repository-relative PDF or image path. |
| `pages` | string or `null` | `null` | PDF page selection such as `"1-5"` or `"1,3,5"`; used by Tesseract. |
| `source` | string | `"repo"` | Source mode. Only `"repo"` is supported. |
| `repo_id` | string | none | Repository containing the file. |
| `method` | string | `"auto"` | `"auto"`, `"databricks"`, `"snowflake"`, `"tesseract"`, `"on_device"` (macOS/Windows), or `"vision"` (images only). |
| `connection_id` | string | none | Databricks or Snowflake connection; auto-detected for `method="auto"`. |
| `databricks_volume_path` | string | `"/Volumes/workspace/default/ocr_temp"` | Databricks upload location. See [OCR volume configuration](https://docs.genesiscomputing.com/docs/Setup/Advanced-Settings.md#ocr-volume) for path selection and Databricks App requirements. |
| `snowflake_stage_name` | string | `"OCR_STAGE"` | Snowflake stage for document upload. |
| `snowflake_database` | string or `null` | `null` | Database for the Snowflake stage; defaults to the connection's current database. |
| `snowflake_schema` | string or `null` | `null` | Schema for the Snowflake stage; defaults to the connection's current schema, or `PUBLIC` if there is no current schema and that schema exists. |
| `snowflake_mode` | string | `"OCR"` | Snowflake `AI_PARSE_DOCUMENT` mode: `"OCR"` or `"LAYOUT"`. |
| `databricks_schema_version` | string | `"2.0"` | Databricks `ai_parse_document` schema version. |
| `databricks_description_element_types` | string | `""` | Databricks description element types: `""`, `"figure"`, or `"*"`. |
| `save_to_git` | boolean | `false` | Save extraction output to Git and return metadata with a preview. |
| `save_all_outputs_to_git` | boolean | `false` | Save both OCR and visual-analysis outputs to Git. |
| `git_path` | string or `null` | `null` | Target Git path when saving OCR output. |
| `provider_timeout_seconds` | integer | `300` | Timeout per OCR provider attempt; `0` disables the timeout. |
| `visual_page_analysis` | boolean | `false` | Render PDF pages and run vision analysis as an additional verification step. |
| `visual_page_analysis_query` | string or `null` | `null` | Optional prompt for per-page vision analysis. |
| `visual_page_analysis_max_pages` | integer | `0` | Maximum PDF pages to analyze visually; `0` means all pages. |
| `visual_page_analysis_dpi` | integer | `150` | PDF screenshot rendering DPI; range `72`–`300`. |
| `visual_page_analysis_save_to_git` | boolean | `false` | Save full visual-analysis output to Git and return a preview with metadata. |
| `visual_page_analysis_git_path` | string or `null` | `null` | Target Git path for visual-analysis output. |

OCR failure responses may include `provider_error_code` when available. Snowflake OCR failures
also identify the failed stage with `failed_step`: `create_stage`, `put_file`, or
`parse_document`. Completed OCR responses include `Route`, which identifies the route that
read the file and any provider that failed first, and `Tell_User`, which asks the agent to
report that route in its answer. For Snowflake stage permissions, see
[Snowflake OCR stage access](https://docs.genesiscomputing.com/docs/Integrations/Data%20Sources/Snowflake/Snowflake#snowflake-ocr-stage-access).

```python theme={null}
ocr(
    filepath="contracts/scanned-agreement.pdf",
    repo_id="legal_docs",
    method="databricks",
)
```

### **`pdf_parser`**

Parse a PDF stored in a Git repo. `source="repo"` is the only supported mode;
URLs and the deprecated `bot_storage` source are not supported.

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **filepath** | Relative path to the PDF file within the repository. | String |
| **source** | Deprecated. Only `repo` is supported. Default: `repo`. | String |
| **repo\_id** | Repository ID that contains the PDF. Required when `source="repo"`. | String |
| **save\_to\_git** | Save extracted text back into the repo instead of returning the full text inline. Default: `false`. | Boolean |
| **git\_path** | Target repo path when `save_to_git=true`. Default: `extractions/&lt;filename&gt;.txt`. | String |
| **start\_page** | First page to read, 1-based. Default: `1`. | Integer |
| **end\_page** | Last page to read, inclusive. Default: the last page; a value past the end reads to the end. | Integer |

Text is returned in reading order: two-column pages are read column by column, and cells in
bordered tables are separated by tabs. Inline output ends on a whole-page boundary at the
reply size limit. The response includes `pages` (`start`, `end`, `total`, `next_start_page`,
and `truncated`) and a `Truncation_Note` when the reply limit stopped the read. If
`truncated` is true, continue with `start_page=pages.next_start_page`. If `pages.page_cut` is
true, one page alone exceeded the limit; only its beginning is returned, so use
`save_to_git=true` to save all extracted text into the repository. A `start_page` beyond the
document returns an error naming the page count.

Each page's extracted text also includes a `Form fields:` section for filled form values and
checkbox states; empty fields, buttons, and signatures are omitted. If the PDF has form
widgets but Genesis cannot read its form values, the page says so. A page may also include
`Text that may be invisible on the page (white on nothing, or under 2 pt):` followed by text
runs that appear near-white without a darker backdrop or are smaller than 2 pt. Treat these
as possible visibility issues to check against the page, not as a determination that the
text is hidden or meaningful.

> [!NOTE]
>
> `bot_id`, `thread_id`, and `user_id` are injected from the current tool
> context. On managed remote repos, Genesis reads the PDF from the active WIP
> worktree when available; otherwise it parses the current remote file contents
> instead of the shared local clone.

> [!NOTE]
>
> When `save_to_git=true` on a managed remote repo, Genesis requires a WIP
> worktree and writes the extracted text there. If one is not selected, call
> `file(action="read", repo_id="&lt;repo&gt;", file_path="&lt;path&gt;",
>     artifact_type="&lt;type&gt;", artifact_id="&lt;id&gt;")` to select or create
> it, then retry. The tool returns
> `error_code="MANAGED_REMOTE_SAVE_REQUIRES_WIP"` when a WIP worktree is
> required; if managed-artifact registry status cannot be read, it returns
> `error_code="MANAGED_REMOTE_SAVE_STATUS_UNKNOWN"` and recommends retrying
> when the registry is available or parsing read-only with `save_to_git=false`.

```python theme={null}
pdf_parser(
    filepath="contracts/master-service-agreement.pdf",
    repo_id="legal_docs",
    start_page=10,
    end_page=20,
    save_to_git=True
)
```

### **`markdown_to_pdf`**

Convert a repo Markdown file into a PDF saved back into a Git repo. Genesis can
render Mermaid diagrams and Plotly charts during conversion. Each render runs
on the browser event loop rather than the server event loop and has a 120-second
budget; a timed-out render is cancelled and the tool returns an error.

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **source\_path** | Repo-relative Markdown file to convert. You can also prefix the repo inline as `repo_id:path/to/file.md`, for example `uploads:thread-1/poem.md`. | String |
| **repo\_id** | Repository that contains the source Markdown and receives the generated PDF. Default: `bot_git`. When `source_path` includes a repo prefix, Genesis uses that repo and any explicit `repo_id` must match it. | String |
| **output\_filename** | Optional output filename. When omitted, Genesis uses the source filename stem and appends `.pdf`. | String |
| **destination\_path** | Optional repo-relative directory for the output PDF. Default: repo root. | String |
| **render\_mermaid** | Render Mermaid diagrams in the generated PDF. Default: `true`. | Boolean |
| **render\_plotly** | Render Plotly charts in the generated PDF. Default: `true`. | Boolean |

```python theme={null}
markdown_to_pdf(
    source_path="reports/analysis.md",
    repo_id="bot_git",
    destination_path="exports/",
    output_filename="analysis.pdf"
)
```

> [!NOTE]
>
> `source_path` can also carry the repo directly, such as
> `uploads:thread-1/poem.md`, when the source document lives outside the
> default `bot_git` repository.

> [!NOTE]
>
> Successful `markdown_to_pdf` responses include `pdf_path`, `repo_id`,
> `git_url`, `download_link`, and `file_size`. `git_url` is a root-relative
> Genesis link, resolving as `/api/git/...` in standalone and local deployments
> and `/git/...` in SPCS.

In a Databricks App deployment without Chromium, `markdown_to_pdf` returns a
clear unavailable error before rendering starts. Save the document as Word
(DOCX) or HTML instead; HTML keeps Mermaid and Plotly diagrams for rendering
when opened in a browser.

> [!NOTE]
>
> In the Git browser and file preview, DOCX downloads now render fenced
> `mermaid` and `plotly` blocks as inline images in the generated Word
> document. Plotly DOCX exports also resolve `data_source.query_id`
> references before rendering so Word output stays aligned with
> `markdown_to_pdf`. If rendering is unavailable, Genesis inserts a short
> placeholder line instead of the raw diagram or chart source.

### **Bulk Pattern File Operations**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **source\_patterns** | List of repo-relative glob patterns or exact file paths to copy or move. | Array of Strings |
| **file\_patterns** | List of repo-relative glob patterns or exact file paths to delete. | Array of Strings |
| **target\_path** | Destination directory for `copy_files` and `move_files`. | String |
| **target\_repo\_id** | Optional target repository id for cross-repo `copy_files` and `move_files`. | String |
| **preserve\_structure** | For `copy_files` and `move_files`, preserve nested paths under the matched pattern scope. Default: `true`. With `source_patterns=["src/**/*"]`, `src/sub/file.txt` becomes `target/sub/file.txt`; exact file paths strip only their parent directory. | Boolean |
| **overwrite** | For `copy_files` and `file(action="copy")`, overwrite an existing target file. Default: `false`. | Boolean |
| **exclude\_patterns** | Optional patterns to exclude from matching. | Array of Strings |
| **dry\_run** | For `move_files` and `delete_files`, preview matches and planned changes without modifying files. Default: `false`. | Boolean |

For `copy_files` and `file(action="copy")`, set `dry_run=true` to inspect a
read-only copy plan. When source files match, the response includes
`dry_run: true`, `would_copy_count`, and up to 10 `planned_files` with source,
target, and size; `copied_count` stays zero because no files are written.
Managed-remote repositories are refused with
`error_code: "COPY_PREVIEW_MANAGED_REPOSITORY"`, including existing WIP
worktrees, because resolving them can create or refresh a worktree. Use an
ordinary local repository for a copy preview.

```python theme={null}
git_action(
    action="copy_files",
    source_patterns=["reports/monthly/summary.md"],
    target_path="archive/",
    preserve_structure=True
)
# Writes archive/summary.md
```

> [!NOTE]
>
> Directory references are auto-expanded for `copy_files`, `move_files`, and `delete_files`. When `preserve_structure` is `true`, glob patterns keep the nested path below the matched parent scope. Exact file paths use their parent directory as that scope, so `source_patterns=["reports/monthly/summary.md"]` writes `archive/summary.md` instead of `archive/reports/monthly/summary.md`.

> [!NOTE]
>
> `copy_files` applies **symlink confinement** on the source repo: matched entries whose
> real path resolves outside the source root are refused (not copied) and recorded in
> `escaped_symlinks` (up to 10 entries) with `escaped_symlink_count` in the result.
> Refused symlinks are not errors — they prevent external host content from being pulled
> into the destination.

> [!NOTE]
>
> `git_action(action="copy_files")` and `git_action(action="move_files")` stage every
> copied or moved path when `dry_run` is false and the target repo has a git index
> (`move_files` also stages source deletions). Responses include `files_staged` and
> `staged_count`; `staged_count` matches `copied_count` or the target-side
> `moved_count`, not the length of the preview arrays. `copied_files` and
> `moved_files` are display samples only (capped at 10 and 50 entries); use
> `copied_count`, `moved_count`, or `get_status` before `commit` to verify large
> operations.

### **Batch File Reads**

```python theme={null}
file(
    action="read_multiple",
    repo_id="my_repo",
    files=[
        "ddl/CUSTOMERS.sql",
        {"path": "ddl/ORDERS.sql", "start_line": 1, "max_lines": 40},
        {"path": "ddl/PRODUCTS.sql", "start_line": -20, "max_lines": 20},
    ]
)
```

> [!NOTE]
>
> `file(action="read_multiple")` accepts a recommended maximum of 20 files per call and a hard limit of 100. Each `files[]` entry can be a path string or a `{path, start_line, max_lines}` object with its own line window. Total returned content is capped at 200 KB; when that limit is reached, remaining files are reported in `skipped`, `skipped_preview`, and `files_skipped`, and the top-level response adds `continuation_hint`. Large files are automatically truncated to about 20 KB, except structured single-document files (`.json`, `.geojson`, `.xml`, `.yaml`, `.yml`, or extensionless files whose content starts like JSON or XML) that exceed the per-file limit — those entries return `success: false` with an error instead of partial `content`. Successful reads include per-file `content` and `size`; truncated entries are marked with `truncated: true` and can also include `truncation_info`, `continuation`, `encoding`, `file_type`, `total_size`, `returned_size`, `returned_lines`, `total_lines`, `start_line`, `end_line`, `start_byte`, `end_byte`, and `freshness_notice` when Genesis read from a managed checkout with no git remote. If any entry is truncated, the batch response adds a warning explaining how to continue from the correct byte or line offset, and the top-level response includes `files_truncated` with the count of truncated files. Use `file(action="read")` for binary or Excel files.

> [!NOTE]
>
> Very large `list`, `find`, and `unzip` responses are previewed instead of returned in full. `files` and `extracted_files` previews are trimmed to the first `50` paths, and `download_links` previews are trimmed to the first `20` links. Use fields such as `files_preview`, `files_truncated`, `files_omitted_count`, `total_files`, `files_continuation_hint`, `note`, and `narrowing_hint` to narrow `list` or `find` queries, or `extracted_files_preview` and `download_links_preview` to inspect the extracted directory.

### `reclaim_duplicate_repos`

Administrators can review and quarantine duplicate local clones of the same
remote. A copy is reclaimed only when the checks show that removing it will not
lose local work or remove a copy that is still in use. Copies with uncommitted or
untracked files, unpublished commits or stashes, active project or Blueprint
references, linked worktrees, recent use, or an unreadable remote are left alone.

Set `thread_copies=true` to work on a thread's own isolated clones and editing
branches created by `prepare_edit` instead. A user can reclaim their own copies;
an administrator can review everyone's. A copy stays in place while its thread
is working or its work cannot be checked. On an owner's dry run, copies containing
uncommitted files, ignored files, unpublished commits, or stashes appear under
`reclaim_with_loss` with the listed work and a `loss_confirmation` code. Explain
the listed losses and get the owner's explicit agreement before confirming with
`confirm=true` and that code as `confirm_loss`; an administrator cannot use this
confirmation to remove another person's work. Work that changes after the dry run
is kept. Reclaimed copies stay restorable in quarantine for 14 days; owners may
restore their own thread copies, and administrators may restore any entry.

For thread copies, a confirm must also pass `repo_ids` naming exactly the copies
the user agreed to; a confirm without it moves nothing. Use one ID for a request
such as deleting a single copy. The dry run can be narrowed with the same list and
returns `in_quarantine` with restorable entries visible to the caller. Copies
written through Genesis in the last two minutes are held; the dry run says when to
try again, rather than waiting for the write in the current turn.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `confirm` | boolean | `false` | With the default, return a dry-run report. Set `true` only after reviewing and agreeing to the report; each copy is checked again before it moves. |
| `restore` | string or null | `null` | Quarantine entry name from a prior result; restores only that entry. |
| `thread_copies` | boolean | `false` | Review thread-owned isolated clones and editing branches instead of duplicate clones. Any user may review their own; an administrator may review all. |
| `confirm_loss` | string or null | `null` | With `thread_copies=true` and `confirm=true`, the dry run's `loss_confirmation` code; owners pass it only after explicitly accepting the listed loss. |
| `repo_ids` | array of strings or null | `null` | With `thread_copies=true`, narrow the dry run or name the exact copies to move on confirm. Confirm requires this list; do not add copies the user did not approve. |

The dry run moves and deletes nothing and changes no access settings, but it
fetches each inspected copy from its remote to refresh and prune its remote-
tracking refs. Confirmed copies move to quarantine for 14 days, then the
scheduled purge deletes them. Restore an entry before it expires:

```python theme={null}
reclaim_duplicate_repos()  # Review the report first.
reclaim_duplicate_repos(confirm=True)  # Only after the user agrees.
reclaim_duplicate_repos(restore="repo--20261103T120000Z")
reclaim_duplicate_repos(thread_copies=True)  # Review your own thread copies.
reclaim_duplicate_repos(thread_copies=True, confirm=True,
                        repo_ids=["my-copy"])  # Move only the approved copy.
```

The scheduled cleanup runs every six hours and is enabled by default:
`jobs.thread_copy_cleanup.enabled` defaults to `true`, and
`jobs.thread_copy_cleanup.idle_days` defaults to `7`. It quarantines only clean,
fully pushed isolated clones unused for that many days. It also removes finished,
idle editing branches after `git_worktrees.idle_reap_seconds` (default `86400`,
24 hours): their work must be pushed or merged into the default branch, with no
running turn, operation, or Mission/project using the branch. Uncommitted or
unpushed work is listed and kept; ignored build output does not keep a branch.
The `list_repos` cleanup hint describes the seven-day isolated-copy quarantine.

## **Use Cases**

1. **Repository curation**
   * List, read, or batch read repository files to review generated assets before publishing.
2. **Document updates**
   * Write content changes to markdown or config files and commit with a clear message.
3. **One-call save**
   * Save a local report into the repo and auto-attach it to the current task for review.
4. **Change review**
   * Read files or trees from a branch, tag, or SHA, compare refs, share a diff for approval, then apply it and commit.
5. **Release preparation**
   * Create a feature branch, make changes, and track history for a clean audit trail.
6. **PDF ingest**
   * Parse a PDF and store extracted text alongside the original for indexing.

> [!WARNING]
>
> `remove_file`\*\*and \*\* `apply_diff`\*\*can delete or overwrite content. \*\* Verify targets and keep changes committed to reversible branches.

## **Workflow/How It Works**

1. **Discover**
   * `list_files` to scope the repo or `get_status` to see pending changes.
2. **Isolate**
   * `create_branch` and `switch_branch` to work safely on a feature line.
3. **Edit**
   * `write_to_file` for text edits or `save_file` for efficient binary and one-call save and attach.
4. **Review**
   * `show`, `diff`, `generate_diff`, and `get_history` to validate changes before commit.
5. **Publish**
   * For standard repos, `commit` with a descriptive message and confirm via `get_status`. For managed remote sources, keep the staged changes on the per-user WIP branch and open review with `create_pull_request` instead of `commit`.

> [!NOTE]
>
> For binary assets, `save_file` avoids loading file bytes into chat context and pairs well with auto-registration and attachment.

## **Integration Relevance**

* **file\_manager\_tools** to register, attach, download, and paginate file content once saved.
* **project\_manager\_tools** to align commits and artifacts with tasks and milestones.
* **document\_index\_tools** to index committed docs for search and Q\&A.
* **artifact\_manager\_tools** to reference generated outputs with durable links.
* **google\_drive\_tools** when you also need to export or mirror key outputs.

## **Configuration Details**

* Use relative repository paths for `file_path` fields.
* Follow branch naming conventions that match your workflow.
* Write clear `commit_message` values for traceability.
* When `auto_register` is true, provide correct `auto_attach_entity_type` and `auto_attach_entity_id`.
* Keep binary files in appropriate directories to avoid repo bloat.

## **Limitations or Notes**

1. Repository initialization and permissions are required for all actions.
2. Large binaries can slow clone and history operations.
3. Concurrent index mutations from multiple agents are serialized server-side, but concurrent edits to the same file content can still cause merge conflicts that require manual resolution.
4. Network connectivity may be required for remotes and external PDF URLs.
5. Auto-registration depends on the availability of `file_manager_tools`.
6. PDF parsing quality varies based on document structure.

## **Output**

* **Repository cloning**
  * Successful `git_action(action="clone_repo")` responses include `repo_id` and `repo_path`; `repo_path` is the checkout path for the newly cloned repository. Reusing a clone adds `already_cloned: true`; shared handouts also set `read_only: true`. Reused-clone responses include `refreshed` (`fetched_now`, `recent`, or `failed`), `updated_at` (last successful fetch in UTC), `behind_by` (the number of commits on the default branch not in the checkout, or `null` when unknown), `commit` (the checkout's current commit), and `freshness`. A failed fetch may also include `refresh_error`. If every matching clone is busy, Genesis returns `error_code="EXISTING_CLONE_IN_USE"` and does not make another clone.
* **Pull-request information**
  * `git_action(action="get_pull_request_info")` returns pull-request metadata. For GitHub, `include_ci` defaults to `true` and includes the authenticated head-commit CI feeds; set it to `false` when only metadata is needed. See [GitHub Connector Tools — Output](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/GitHub-Connector-Tools.md#output) for the CI fields, completeness signals, and partial-read errors.
* **Bulk pattern file operations**
  * `git_action(action="copy_files")` returns `copied_count`, `skipped_count`, `error_count`, `escaped_symlink_count`, `total_size`, `message`, and a `copied_files` preview (up to 10 entries). With `dry_run=true`, it instead reports `would_copy_count`, `planned_files` (up to 10 entries), and `dry_run: true` without writing files or staging changes. When staging succeeds, non-preview responses also include `files_staged` and `staged_count` equal to `copied_count`. `git_action(action="move_files")` returns `moved_count`, `collision_count`, `move_errors`, `collisions`, `cleaned_directories`, `message`, and a `moved_files` preview (up to 50 entries), plus `files_staged` and `staged_count` for target additions when staging succeeds.
* **File Operations**
  * For capped `git_action(action="read_file")` and `file(action="inspect_structured_data")` results, follow the shared spill guidance in [Code Executor Tools — Output](https://docs.genesiscomputing.com/docs/Genbot-Toolkit/Code-Executor-Tools.md#output), including what to do when the spill save fails.
  * Confirmations for create, modify, remove, single-file reads, and batch read results with per-file success or error details plus `content` and `size` for successful reads. Managed base-checkout reads from a checkout with no git remote include `freshness_notice` and may set `source` to `local_tree`. For `file(action="search_replace")` and `file(action="edit")`, applied edits return counts plus `changed_line_count` and a bounded `changed_lines` sample by default; pass `return_verbose_edit_result=true` (or `dry_run=true` for a no-write preview) to also receive the before/after `preview`, and for `edit` the per-edit `changes` array. For unpaged reads that would clip structured single-document files (`.json`, `.geojson`, `.xml`, `.yaml`, `.yml`, or extensionless files whose content starts like JSON or XML — detected by extension or content sniffing), Genesis returns `success: false` with `error`, `total_size`, `truncated: true`, and `content_preview` but omits `content`. `max_bytes` (alias `max_chars`) caps returned content in bytes. `return_base64=true` on unpaged reads returns a size-limited partial with `truncated=true` and a byte-range `continuation`; it does not bypass this refusal, and clipped JSON/XML payloads may include `structured_partial_warning`. `file(action="read")` always returns inline `content` sized to the file-read budget, with `truncated` and/or `size_capped` when more remains; a line longer than the budget can return `partial_line` and requires `start_byte`/`max_bytes` to continue. Batch reads can also surface per-file `truncated`, `size_capped`, `partial_line`, `truncation_info`, `continuation`, `encoding`, `file_type`, `total_size`, `returned_size`, `returned_lines`, `total_lines`, `start_line`, `end_line`, `start_byte`, `end_byte`, and `freshness_notice`, plus top-level `warnings`, `files_truncated`, `files_skipped`, `skipped_preview`, and `continuation_hint` when the response is cut short. `git_action(action="read_file")` and `file(action="inspect_structured_data")` can still return `tool_output_capped`, `preview`, `truncation_info`, `full_output_ref`, and `agent_guidance`; in that envelope, `truncation_info` includes `bucket`, `bytes_in`, `bytes_out`, `budget_bytes`, and `spill_path`.
  * `file(action="search")` returns at most `max_results` matching-line records (default `100`, hard maximum `1000`). `total_matches` is exhaustive only when `total_matches_is_exact=true`; if counting times out or partially fails, usable results are retained, `total_matches_is_exact=false`, and `total_matches` covers successfully counted portions. `returned_matches` reports the records included in the response. Repository-wide searches return count metadata only (`returned_matches=0`, `results=null`); pass `file_path` to return matching text. Matching lines, not individual occurrences within a line, are counted. Lowering `max_results` limits returned text but does not reduce the filesystem work required to count matches. Direct `git_action(action="search")` supports `context_lines` from `0` through `20`; the public `file` wrapper uses `2` context lines.
  * Failed `file(...)` mutations return `success: false` with `error`, `failed_operation`, `file_path` (when applicable), and `exception_type`. The `error` string names the operation and target file (for example `write_file on 'docs/query.sql' failed: RuntimeError: index corrupt`) and includes the exception class and message. For `OSError` subclasses whose message omits the affected path, Genesis also appends `(path: '...')` so you can tell a failed write from failed git housekeeping such as index staging. Staging failures after a successful write say `staging in git index failed` instead of implying the write itself failed. Credentialed remote URLs embedded in error text are redacted as `https://***@host/...`.
  * Successful `file(...)` mutations on remote-backed repos can proceed when a required pre-mutation fetch fails. Those responses include `warnings` (and optionally `hints`) with the fail-open notice, plus `_auto_fetch_warning` and `_auto_fetch` metadata. Genesis states each distinct error or hint once — the same git error is not repeated across `warnings`, `_auto_fetch_warning`, nested `_auto_fetch` fetch results, and `details.raw_error`.
* **Ref-scoped file reads**
  * `git_action(action="show")` returns `content`, `encoding`, `resolved_ref`, `branch_name`, `commit_sha`, `sha`, `size`, `truncated`, and `max_chars`. Binary reads also include `binary=true`. When content is clipped, `truncation_notice` explains how to pass a larger `max_chars`.
* **Tree and Ref Diffs**
  * `git_action(action="ls_tree")` returns `entries`, `count`, `truncated`, `max_entries`, `path`, `recursive`, `resolved_ref`, `branch_name`, and `commit_sha`. `git_action(action="diff")` returns either `patch` with `max_chars` and optional `stats`, or `name_status_entries` with `count` and `max_entries`, plus `from_ref`, `to_ref`, `from_commit_sha`, `to_commit_sha`, `path`, and `truncated`.
* **Diff and Apply**
  * Unified diff output and application results.
* **Commit and Branch**
  * Commit hash, affected files, and branch confirmations for standard repos. Successful commits can include `auto_healed: true` when Genesis rebuilt a corrupted local clone from remote during the commit preflight. When only unneeded loose objects are damaged (nothing refers to them), successful commits can also include `integrity_warnings`, `damaged_object_paths`, and `integrity_hint` with guidance to run `quarantine_corrupt_objects`. Corruption failures return `error_code: GIT_REPOSITORY_CORRUPTED` with `validation`, `recovery_options`, and optional `auto_heal_attempted`. When `recovery_options` reports damaged but unneeded loose objects, it can list `warnings`, `unneeded_object_paths`, and a `quarantine_corrupt_objects` option with `data_loss_risk: "none"`. When a damaged object is still referred to, `recovery_options` can include `needed_object_ids`, `needed_object_paths`, `staged_files_for_needed_objects`, a `warning` or `recommendation`, and — when every needed object is staged from the working tree — a `restore_object_from_working_tree` option with `data_loss_risk: "none"`.
  * `git_action(action="commit", dry_run=True)` returns a read-only preview envelope (`dry_run: true`, no `commit_hash`) with `already_staged`, `would_stage`, `would_commit`, `changed_files`, `untracked_files`, `conflicted_files`, `remaining_conflicted_files`, `diff_summary`, `can_commit`, `preview_exact`, optional `staging_would_fail`, `rejected_stage_paths`, `unmatched_stage_paths`, and an `uncertainty` object when transforms or unsupported entry types prevent an exact preview. Failures set `success: false` with `error` and may include `error_code`, `unmatched_stage_paths`, or `rejected_stage_paths`.
* **Repository integrity**
  * `git_action(action="quarantine_corrupt_objects")` returns `success`, `message`, `quarantined`, `quarantine_dir`, and `repository_valid_after` on success. Failures return `error` with optional `needed_object_ids`, `staged_files_for_needed_objects`, `fsck_output`, `skipped`, and `fsck_output_after`.
* **Index lock recovery**
  * `git_action(action="force_unlock")` returns `success`, `message`, and `lock_file` when `index.lock` is cleared (or was already absent). Failures return `error`, `lock_file`, and optional `recovery_hint`. When automatic retries still fail, commit and other index mutations can return `lock_detected: true` with `recovery_action` and `recovery_hint` instead of a generic error alone.
* **Remote sync**
  * `git_action(action="push")` returns `branch` and `refs_pushed` on success. Bare push and explicit `branch_name` both set upstream tracking on the remote branch. Bitbucket Cloud uses `git push` with the saved connection credentials, preserving the local commit and history; it also passes the same code-scan preflight as other Git hosts. Without `push_timeout_seconds`, its push is bounded to five minutes.
  * `git_action(action="pull")` returns a success message that includes the merge/rebase `strategy` used.
  * When `fetch` or `pull` fails because the repository's connection is unavailable to you, cannot sign in, or is refused by the host, Genesis can try up to three of your own usable connections configured for that host. A connection that reaches the repository is used for that call only; the repository keeps its configured connection. The response's `connection_fallback` identifies the attempted and selected connections. Passing `connection` explicitly disables fallback. Fetches run automatically before reads or edits never fall back.
  * When the current branch cannot be resolved (detached HEAD) or Git reports no upstream tracking, push and pull return `error_code="git_no_upstream_branch"` with `remediation.action="set_branch_name"` — retry with `branch_name='<branch>'`.
  * `git_action(action="fetch")` returns changed refs in `updates`. Each update includes `ref`, `branch`, `old_commit`, `new_commit`, and `flag`, where `flag` is one of `fast_forward`, `forced_update`, `new_head`, `new_tag`, `tag_update`, `rejected`, `error`, or `other`. Refs already up to date are excluded from `updates`; `no_op=true` identifies a successful fetch with no changed refs, `current_head_commits` maps fetched refs to their current SHAs, and `branches_updated` counts only changed refs.
  * `git_action(action="list_connections")` reports `usable_by_you`, a status, and per-host `health` and `git_access`. A host is `connected` only after a fetch or pull reached it; `health` is unmeasured until then. `org_access_restricted` names GitHub organizations that block the OAuth app and includes what to ask an owner. `list_remote_repos` reports the same organization restriction instead of silently omitting the organization.
  * Managed-remote branch fetches for ref reads use the origin connection's credentials, using the supplied `connection` when present or the connection resolved for that remote. When push, pull, fetch, clone, or other remote git operations fail, Genesis returns a normalized payload with `success: false`, `error_code` (for example `git_operation_failed`, `git_timeout`, `git_network_error`, `git_no_upstream_branch`, `git_auth_failed`, `git_credentials_not_applied`, `git_authz_denied`, or `git_authz_scope_insufficient`), credential-redacted `error`, and `details` containing `operation`, `repo_id`, `remote_url`, `connection`, `connection_type`, `connection_name`, `exception_type`, and `errno_path` when the underlying exception carries a filesystem path. `git_credentials_not_applied` means Git sent no credentials for the operation, rather than credentials being rejected; its remediation is to check that the remote has a connection (using `list_remotes` or `configure_remote`) or pass `connection` explicitly. `details.raw_error` is omitted when it would duplicate `error` (the usual case). Optional `remediation` includes `action` and `message` guidance (for example `check_connection_credentials` after an auth failure).
* **Managed source protection**
  * Direct base-checkout mutations on managed remote sources return `success: false` with `error_code`, `error`, `managed_repo_guard`, `next_steps`, and `registry_lookup_failed`. When staged `copy_files` or `delete_files` operations target a managed source, `next_step` directs you to `create_pull_request` on the per-user WIP worktree instead of `commit`. When a blocked **mutation** (`git_action` mutating actions or `file` write/delete/copy/move actions) targets a repo that hosts a registered documents (Knowledge Base) artifact, the response also includes `managed_document_repo: true` and KB-specific `next_steps` (with a `source_id_or_index` hint) pointing to `propose_kb_edit` and `open_kb_pull_request` — not the generic WIP worktree flow. Blocked **reads** do not include KB steering. For managed document feeds, stage markdown with `propose_kb_edit` or `/api/managed-sources/{source_id}/workspace/propose` instead of direct index mutations or `file(action="write")`.
* **History and Status**
  * Commit lists with timestamps, authors, and messages, plus working tree status.
* **Repository Discovery**
  * `git_action(action="list_repos")` returns visible repo ids. With `details=True`, each detail row includes `mode`, `kind`, `has_git_dir`, `has_remote`, `scope`, `owner_user_id`, `owner_bot_id`, and `undeletable`, plus credentials-redacted `remote_url` when present, `clone_source` when Genesis can infer the remote platform, and `path` when `include_paths=True`. `kind` is `git_repository` for entries that accept git actions and `storage_workspace` for storage-only entries. The detailed response also includes `git_repositories`, `storage_workspaces`, and `git_repository_ids`; these counts and ids cover the whole visible listing, not just the current page. `mode` is the repository's effective mode, while `has_git_dir` reports the physical `.git` entry, so a reserved storage-only repository can have `mode: "storage"` and `has_git_dir: true`. When RBAC hides repos, the response can include `hidden_by_access_count`. Passing `repo_id` performs an exact or resolved existence check: a local id match returns `exists: true`; a remote org/name or URL resolves to the visible local clone and can return `matched_by`, `resolved_from`, and `remote_url`. No match returns `error_code="REPO_REFERENCE_NOT_FOUND"`; multiple matches return `error_code="REPO_REFERENCE_AMBIGUOUS"` with `candidates`. If detailed discovery finds unregistered blueprint repositories, `unconfigured_repos` and a count-aware `unconfigured_next_step` explain that the user must register them in the Blueprint dashboard; see [Blueprint Library and Missions](https://docs.genesiscomputing.com/docs/Blueprint/Blueprint-Library-And-Missions.md#main-library-actions).
  * If detailed results include remote-backed clones, each row has `remote_group`; `provenance` includes `kind` and `created_at`. It includes `created_by_user_id`, `created_by_bot_id`, and `created_thread_id` only for the matching `created_by_user_id` or an administrator, so another viewer does not learn a private thread ID from the copy name. When multiple clones of one remote appear on the page, `duplicate_of` points each extra copy to the preferred clone and is `null` on that preferred row. `duplicate_summary` counts extra copies on the current page. The preferred clone is this thread's isolated copy when present, otherwise the clone named like the remote, otherwise the most recently fetched.
  * When detailed results include multiple clones of one remote, each matching row has `remote_group`; recorded provenance appears in `provenance`, and `duplicate_of` points extra copies to the preferred clone (`null` on the preferred row). `duplicate_summary` counts extra copies in the current page. The preferred clone is this thread's isolated copy when present, otherwise the clone named like the remote, otherwise the most recently fetched.
* **Repo reference resolution**
  * Repo-scoped actions that resolve a remote reference attach `resolved_repo_id`, `resolved_from`, and `matched_by` to successful responses when the caller passed a remote org/name or URL instead of a local clone id. When multiple visible clones match the same remote, the response also includes `selected_by` and `other_copies`.
* **Blocked GenesisApp mutations**
  * Bulk or unsupported `file(...)` mutations through `repo_id="apps"` that target a registered GenesisApp workspace return `success: false` with `error`, `next_steps`, `blocked_by`, `app_id`, `rel_path`, and `matched_param`. Supported single-file mutations are routed to the app workspace instead; see the guidance above.
* **Large Path and Archive Previews**
  * `file(action="list")` and `file(action="find")` can return `files_preview`, `files_truncated`, `files_omitted_count`, `total_files`, `files_continuation_hint`, `note`, and `narrowing_hint` when many paths match. `file(action="unzip")` can similarly preview `extracted_files` and `download_links` with fields such as `extracted_files_preview`, `extracted_files_truncated`, `extracted_files_omitted_count`, `total_extracted_files`, `extracted_files_continuation_hint`, `download_links_preview`, `download_links_truncated`, `download_links_omitted_count`, `total_download_links`, and `download_links_continuation_hint`.
* **Auto-switch to default branch**
  * On the first eligible content read per thread/session/repo key, `file(...)` and `git_action(...)` responses can include `_auto_branch_switch`. When Genesis switches the clone, the object has `auto_switched: true`, `from_branch`, `to_branch`, and `message`. When the switch is skipped, it has `auto_switch_skipped: true`, `reason` (for example `dirty_working_directory` or `switch_failed`), `current_branch`, `default_branch`, and `message`. A `dirty_working_directory` skip means modified, staged, conflicted, or user-owned untracked paths are present; Genesis internal untracked metadata (`.genesis/`, `.genesis-sync.lock`, `.genesis-sync.lock.lock`) does not count as dirty.
* **Zero-result repo search warning**
  * `git_action(action="search")`, `git_action(action="grep")`, `file(action="search")`, and `file(action="fast_search")` can include a `_branch_warning` object when `total_matches` or `count` is `0` and the repo is on a non-default branch. The object includes `current_branch`, `default_branch`, and `message`, which directs you to switch to the default branch, run `git_action(action="pull")`, and retry the search.
* **Managed-remote search freshness**
  * On managed remote repos, `git_action(action="search")` and `git_action(action="grep")` against the managed base checkout run against refreshed origin state instead of the shared local clone. Searches against a WIP worktree still use that worktree. When the managed checkout has no git remote, `file(action="fast_search")` searches the local checkout and includes `freshness_notice` instead of failing mirror preparation. `file(action="list")` and default managed `file(action="read")` follow the same local-tree fallback with `freshness_notice`.
* **PDF Parsing**
  * Extracted text and metadata ready for indexing or analysis. When `save_to_git=true`, responses also include `Saved_To_Git`, `Repo_ID`, `Git_Path`, `Total_Characters_Extracted`, `Content_Preview_Only`, `Context_Limit_Bypassed`, `Stats`, `Warnings`, and a truncated `Content` preview.
