Team Sync (Command Reference)

The team story — roles, the two-way join gate, conflict policy, CI on the corpus — is in Teams: Sharing the Vault. This page is the command reference.

Team sync is the deployment story: one fabric per machine, one corpus shared via git. Configure the corpus remote in Configuration or at install time.

One fabric per machine, one corpus shared via git. Throughout the docs: the fabric is your local knowledge base; the corpus is the shared subset of it that syncs to your team remote. wf sync pushes/pulls that content (claims, sources, patterns, experience events, registry) to a git remote — a private GitHub repo works well. The harness (scripts, schemas) stays per-machine and updates via wf update from the public repo; content and code have different lifecycles and remotes.

First-time setup: wf sync setup

wf sync setup is the initial-setup step that makes the fabric a team system. It uses the gh CLI (checked at run time — install gh and run gh auth login if missing) to:

1. Create the corpus repo — <owner>/wiki-fabric-corpus, private by default (--public to flip). Prompts before creating unless -y.
2. Publish your fabric's corpus as the source of truth: sync init makes the corpus a standalone git repo (<fabric>/corpus/.git), commits the content, and pushes to the remote's main (remote root == corpus content — no prefix/branch aliasing).
3. Print the teammate one-liner — teammates inherit the team's knowledge from their first install command.

If gh isn't available, setup prints the manual path instead (gh repo create by hand, or wf sync init <url> pointing at an existing repo). The corpus holds your project knowledge — the privacy default is deliberate. Note: wf sync setup/init scaffold AGENTS.md at the fabric/vault root if it lacks one (a fresh fabric needs the marker to sync).

Day-to-day, on any machine

wf sync status        # ahead/behind + uncommitted corpus changes + conflicts
wf sync commit-drift  # stage + commit hook-accumulated drift (plane-classified; never pushes)
wf sync push -m "ingested upstream docs"   # commit + push corpus changes
wf sync pull          # fetch + merge; conflicts → review queue

The drift-wave ritual: hooks capture and ingest between human commits — a day's work leaves dozens of modified corpus files. wf sync commit-drift stages everything and commits with a plane-classified summary (atom/ evidence/registry counts, worst-plane tag in the message: drift [knowledge-update]: 2 atom(s), 24 evidence(s), …). Idempotent (clean tree → exit 0), dry-run-able, and never pushes — push stays the explicit publish step. sync setup/init also scaffold registry/promotion-queue.md and questions/.

Branches, in one line: there aren't any — the corpus is a standalone repo (<fabric>/corpus/, cloned or init'd in place); the remote's root IS the corpus content. Push = git push origin main from inside the corpus (rejected when the remote moved — pull first, never force); pull = plain merge. Team mode adds a per-push branch sync/<machine>-<stamp> whose PR squash-merges to main. Full model + rationale: Teams › The branch model.

Team mode (PR-gated distribution): fabric.yaml → sync: {mode: team, evidence_prs: auto}. Every push opens one PR (branch sync/<machine>-<stamp>, body carries the change-set receipts + files classified by plane). Evidence-plane-only PRs auto-merge when CI is green; anything touching atoms (claims, patterns, decisions, projects) waits for human review — never auto-merged. Per-invocation: --pr opts in even solo; --no-pr opts out even team mode.

A teammate joins — two commands (tool install → fabric + join; install pulls the corpus when the remote already carries one; --vault pins where the vault shell lives):

uv tool install wiki-fabric --with mcp     # any platform (POSIX fallback: the curl one-liner, see Teams)
wf install --corpus git@github.com:your-org/wiki-fabric-corpus.git --vault ~/knowledge/vault

Manual join (existing install): wire the remote + pull:

git remote add corpus git@github.com:your-org/wiki-fabric-corpus.git
wf sync pull

Config layering (who gets routing vs keys vs knowledge): see Teams › Config layering. Short version: routing travels with the project overlay, keys/owner stay machine-local, knowledge syncs with the corpus.

How bootstrap meets the corpus

When you wf bootstrap a project into a fabric with a corpus remote, the bootstrap writes a small projects/<slug>/README.md (title, owner, date, upstream sources) into the namespace — that README syncs to the corpus, so teammates see what the new project is the moment it lands. Bootstrap prints whether the project is local-only or corpus-wired, and wf sync status lists new namespaces waiting on the remote ("New projects on the corpus (pull to receive)"); wf sync pull announces each namespace it delivers, with owner. Teammates discover new projects by pulling — nothing to configure on their side.

Install-time join: two-way gate

install --corpus decides the join direction automatically, by content: the remote is probed (git ls-remote … refs/heads/main); a corpus that exists remotely while the local corpus has no knowledge content ⇒ teammate join — the corpus is CLONED from the team repo into <fabric>/corpus/ (origin pre-wired for your first push). Otherwise ⇒ lead machine (sync init publishes the local corpus). Full detail — both join paths, what happens behind the commands — on Teams › Joining.

Legacy-layout fabrics (outer git tracking corpus/) get a one-time loud advisory on push/pull: run wf sync migrate [url] — corpus/ becomes a standalone git repo, content committed + pushed, outer git untracks it.

Conflict policy: review queue, never silent overwrite

When two machines changed the same file, wf sync pull aborts the merge and writes a conflict record to registry/conflicts/<date>/ containing both versions (ours vs theirs) side by side. The fabric stays clean; you decide. Unresolved conflicts make wf lint fail (SYNC-CONFLICT errors) and block wf sync push, so a disagreement can't sneak into the shared truth.

Resolving:

wf sync resolve <conflict-file>                # interactive: diff + pick
wf sync resolve <conflict-file> --strategy ours|theirs|union   # scripted

The interactive flow shows a unified diff of both versions and prompts — ours (keep this machine's), theirs (take the teammate's), union (keep both, marked for later dedup), skip (leave pending — the gate stays up). The conflict record is consumed on resolve; the resolution is committed so the next push carries it.

Why a separate remote from this public repo

This repo is the public harness; your corpus is your private knowledge. Keeping them on different remotes means wf update (harness) never touches team content, and wf sync never publishes your corpus to a public URL.