# Docs: correct the "active HEAD propagation needs symref-update" claim

`eb10e26`·

Earlier docs framed active HEAD propagation as blocked on a future
go-git change for the `symref-update` receive-pack capability. That
capability doesn't exist in git's wire protocol — gitprotocol-pack.adoc
defines receive-pack commands as create/delete/update only, and
receive-pack's command parser rejects anything else. The symref-update
that exists in git is in `update-ref --stdin`, a local CLI for the ref
backend.

There is no portable wire-level mechanism for updating a remote symref,
which is why `git push --mirror` doesn't either. Reframe the docs to
match: detection is the ceiling for any git-protocol client, and
manual reconciliation (provider REST API or `git symbolic-ref` over
SSH) is the supported path, not a v1 placeholder.

Refs #45.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## Changes

1. **Practical mitigations, in order of preference:**  
   - **Match the default at init time.** `git init --bare --initial-branch=<source-default>` (or the equivalent on your host) avoids the problem entirely. `git-sync probe <source-url>`'s `sourceHead` field tells you what to pass.  
   - **Set HEAD manually post-sync.** On a self-hosted bare repo: `git symbolic-ref HEAD refs/heads/<source-default>`. On hosted providers (GitHub, GitLab, etc.), use the provider's API or web UI to set the default branch.  
   - **Set HEAD out-of-band post-sync.** On a self-hosted bare repo accessible over SSH: `git symbolic-ref HEAD refs/heads/<source-default>`. On hosted providers, use the provider's API (GitHub: `PATCH /repos/{owner}/{repo}` with `default_branch`; GitLab: `PUT /projects/:id` with `default_branch`) or web UI.  
   - **Compare the fields.** A wrapper script that runs `git-sync probe ...` and compares `sourceHead` against `targetHead` will catch mismatches before they bite.

## JSON Output  
```
Mdocs/usage.md+8/-6
```