refactor(config)!: rename repositories[].branch to ref

[christso]

Closes #362.

Two commits:

1. faf36cf — document the managed field and --no-managed flag, which existed in the CLI but on no page of the docs site.
2. ce6f03d — breaking: rename repositories[].branch to repositories[].ref.

Why the rename

repositories[].branch was validated by RepositorySchema and published in the v1 JSON schema, but it never appeared in any documentation — the docs PR in this branch was about to be the first prose description of it. It is renamed rather than deprecated.

It also collided with an existing, documented name for the same concept: plugins[].ref already means "tag or branch" (workspace-config.ts:138, configuration.mdx:437). Newer code already normalizes URL-parsed branches into ref (skill-update.ts:362); repositories[] was the last holdout.

branch never fit the use case anyway. Verified against real git:

Probe	Result
git clone --branch v1.0.0 <url>	Works — lands in detached HEAD
git clone --branch <full-sha> <url>	fatal: Remote branch … not found in upstream origin
simple-git status() on that tag checkout	current: "HEAD"
git pull on detached HEAD	You are not currently on a branch.

So branch could only express a movable pointer, never a pinned revision. ref now names a branch or tag, matching plugin entries.

Why a bare rename would have been a silent break

RepositorySchema is not strict, so replacing the key outright strips a stale one with no error:

naive rename, validation: PASSED
naive rename, parsed value: {"path":"../x"}
=> legacy pin silently discarded: true

A user with branch: release-1.x would have silently started cloning the default branch. So the removed key is declared as never with a migration message:

ref: z.string().optional(),
branch: z
  .never({ error: "has been renamed to 'ref'" })
  .optional()
  .describe("Renamed to 'ref'"),

That produces a precise runtime error and {"description": "Renamed to 'ref'", "not": {}} in both published schemas, so editor validation flags the removed key too.

Surface

repositories[].branch had exactly two consumers (managed-repos.ts:155,168) and zero writers — ref is not accepted elsewhere on repository entries. Changes:

• src/models/workspace-config.ts — ref plus the never guard
• src/core/managed-repos.ts — param rename, call sites, and a note that a tag ref leaves the checkout detached so pull is skipped rather than run against the wrong revision
• docs/public/schemas/v1/*.json — regenerated (bun run schema:generate)
• tests/ — ref accepted and preserved; removed branch rejected with the message; new managed-repos-ref.test.ts captures the git-client boundary to prove ref reaches clone --branch and the pull comparison
• docs — the managed-repo sections now use ref, with a migration note

Verification

bun run typecheck     # clean
bun run lint          # clean, 136 files
bun run schema:generate && bun run schema:check   # regenerated, no drift
bun run docs:build    # 13 pages, clean
bun test tests/unit/core/managed-repos-ref.test.ts tests/unit/core/managed-repos.test.ts \
         tests/unit/models/workspace-config.test.ts tests/unit/models/workspace-json-schema.test.ts
                      # 48 pass, 0 fail

Built CLI against a temp workspace, real exit codes:

Config key	allagents update --no-managed
ref: release-1.x	exit 0
branch: release-1.x	exit 1

$ allagents status
Error: .allagents/workspace.yaml validation failed:
  - repositories.0.branch: has been renamed to 'ref'

Rendered docs/dist checked, not just source: the Managed Repositories section uses ref in every example, with no stale branch: left in either page, and the published ref property is {"type":"string"}.

Known gap this surfaced (pre-existing, not fixed here)

allagents update exits 1 for a project-config validation failure without printing the reason — the multi-pass path only collects thrown errors, while syncWorkspace returns a failedSyncResult for parse failures (sync.ts:2953-2959). Confirmed pre-existing: a repository entry missing path behaves identically. allagents status prints the message correctly. Worth a separate issue; fixing it here would change failure output for every validation error, well beyond this rename.

Migration

Rename branch: to ref: in repositories[]. Nothing else changes; managed, source, and repo are untouched.

[cloudflare-workers-and-pages]

Deploying allagents with    Cloudflare Pages

Latest commit:	ce6f03d
Status:	✅  Deploy successful!
Preview URL:	https://c1547df4.allagents.pages.dev
Branch Preview URL:	https://docs-362-managed-repo-field.allagents.pages.dev

View logs