docs(git-integration): clarify one-way model, repo types, and sync_with_git

[iddocohen]

Summary

Correct and expand the Git Integration overview so it matches how the integration actually behaves. The page previously described the read-write Repository type as "full bidirectional integration" with data flowing "from Infrahub back to Git" — this is inaccurate (and contradicted the page's own ff-only merge statement), and it is the single most common customer misconception hit in the field (Sony, Link11, and others).

Use case: smaller update / feature improvement (no structural change).

Content changes (all in git-integration/overview.mdx)

• Two version-control planes (new section) — establishes the graph (data + schema, versioned in Infrahub's DB) vs Git (code intent) split, and that the link runs one way, Git → Infrahub.
• Repository types — reframed the standard type from "full bidirectional integration" to read-write integration: automatic Git → Infrahub import plus a single narrow write-back (the linked branch's default ref) on Proposed Change merge. Fixed the "creates a merge commit / pushes it back" paragraph to match the ff-only default and to state that only code intent moves, never data.
• Read-only repositories — clarified that they are not polled; you update via ref change or Import latest commit.
• Controlling whether a branch reaches Git (new subsection) — documents the per-branch sync_with_git flag and the common misreading of its name.
• Common misconceptions (new section) — three verified pitfalls.

What needs reviewer attention

New prose to read carefully (the rest is small edits to existing lines):

• "Two version-control planes". Mental model; claims verified against core/branch/models.py, git/tasks.py:696 (merge_git_repository), git/repository.py:271 (merge + push).
• sync_with_git subsection. Matches the field description in core/branch/models.py:40-42 and the PC-merge gate in core/merge/branch_merger.py:286.
• "Common misconceptions". Each item is code-verified; aligns with the UI label fix in ic-clarify-sync-with-git-label (changelog +9883).

What didn't change

• No claims invented; every new statement traces to backend code.
• The ~60s poll interval from field notes was intentionally not added — it isn't sourced from code, and the page already hedges ("multiple times per minute").

Out of scope (deferred, not touched)

• Pre-existing voice drift ("bridges these two worlds"; "simpler, unidirectional") left as-is to keep this PR scoped. Small follow-up.
• Multi-environment promotion content (three pages in flight elsewhere).

Verification

• markdownlint-cli2 (repo .markdownlint-cli2.yaml): 0 issues.
• Vale: 0 errors, 0 warnings, 0 suggestions.
• Word check (simple/easy/just): none in new content.
• cd docs && npm run build not run locally — docs deps not installed in this checkout; relying on CI for the render check.

[cubic-dev-ai]

2 issues found and verified against the latest diff

Confidence score: 4/5

• In docs/docs/git-integration/overview.mdx, the write-back behavior is currently described as if every Proposed Change merge updates Git, but branches with sync_with_git disabled stay graph-only; this can mislead operators into expecting commits that never occur and cause workflow confusion—update the wording to explicitly gate Git write-back on the source branch’s sync_with_git state.
• In docs/docs/git-integration/overview.mdx, terminology for Infrahub features is inconsistently cased ("transformations"/"generators"), which risks style-guide drift and inconsistent docs voice—capitalize these feature names to match AGENTS.md guidelines.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/docs/git-integration/overview.mdx">

<violation number="1" location="docs/docs/git-integration/overview.mdx:7">
P3: The Infrahub style guide requires capitalizing "Transformations" and "Generators" when referring to these features (see AGENTS.md → Style Guidelines → Infrahub Terminology). In the new introductory text and the "Two version-control planes" section, both terms appear lowercase, which is inconsistent with the guide and with how they are styled in the rest of the docs (e.g., `connect-repository.mdx` uses "Transformations, Generators").</violation>

<violation number="2" location="docs/docs/git-integration/overview.mdx:35">
P2: A read-write repository does not update Git on every Proposed Change merge: branches with `sync_with_git` disabled remain graph-only. These statements should condition the write-back behavior on the source branch's `sync_with_git` value so the overview does not contradict its own branch-control section.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: A read-write repository does not update Git on every Proposed Change merge: branches with sync_with_git disabled remain graph-only. These statements should condition the write-back behavior on the source branch's sync_with_git value so the overview does not contradict its own branch-control section.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/git-integration/overview.mdx, line 35:

<comment>A read-write repository does not update Git on every Proposed Change merge: branches with `sync_with_git` disabled remain graph-only. These statements should condition the write-back behavior on the source branch's `sync_with_git` value so the overview does not contradict its own branch-control section.</comment>

<file context>
@@ -23,15 +30,15 @@ Modern infrastructure management requires both structured data (network configur
+### Repository: read-write integration
 
-The standard **Repository** type provides comprehensive, bidirectional integration between Infrahub and Git. This design choice fulfills the need for truly unified version control across infrastructure data and code.
+The standard **Repository** type gives Infrahub read-write access to Git. Infrahub imports code from every branch automatically, and on a Proposed Change merge it updates the repository's default branch in Git.
 
 **Design principles:**
</file context>

[cubic-dev-ai]

P3: The Infrahub style guide requires capitalizing "Transformations" and "Generators" when referring to these features (see AGENTS.md → Style Guidelines → Infrahub Terminology). In the new introductory text and the "Two version-control planes" section, both terms appear lowercase, which is inconsistent with the guide and with how they are styled in the rest of the docs (e.g., connect-repository.mdx uses "Transformations, Generators").

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/git-integration/overview.mdx, line 7:

<comment>The Infrahub style guide requires capitalizing "Transformations" and "Generators" when referring to these features (see AGENTS.md → Style Guidelines → Infrahub Terminology). In the new introductory text and the "Two version-control planes" section, both terms appear lowercase, which is inconsistent with the guide and with how they are styled in the rest of the docs (e.g., `connect-repository.mdx` uses "Transformations, Generators").</comment>

<file context>
@@ -4,11 +4,18 @@ title: Git Integration
 import ReferenceLink from "../../src/components/Card";
 
-Git Integration in Infrahub connects your data layer to external Git repositories, letting you store and version-control the code that drives Infrahub — transformations, generators, checks, and other automation resources — alongside your infrastructure data. This page covers the underlying concepts; specific tasks like [connecting a repository](./connect-repository.mdx), [configuring `.infrahub.yml`](./infrahub-yml.mdx), and [filtering which branches sync](./branch-synchronization.mdx) live in the pages below.
+Connect an external Git repository to keep the code that drives Infrahub — schemas, transformations, generators, checks, GraphQL queries, and artifact definitions — under version control, next to your infrastructure data. Infrahub imports that code and keeps it in sync as the repository changes.
 
-## Understanding Git repositories in Infrahub
</file context>

Suggested change

	Connect an external Git repository to keep the code that drives Infrahub — schemas, transformations, generators, checks, GraphQL queries, and artifact definitions — under version control, next to your infrastructure data. Infrahub imports that code and keeps it in sync as the repository changes.
	Connect an external Git repository to keep the code that drives Infrahub — schemas, Transformations, Generators, checks, GraphQL queries, and artifact definitions — under version control, next to your infrastructure data. Infrahub imports that code and keeps it in sync as the repository changes.