feat(release)!: ship Ragmir v3 with safe team sync

AGENTS.md

@@ -20,9 +20,12 @@
 - Long-running Node.js processes use one `RagmirClient` per project root and close it during shutdown. Keep the top-level API for one-shot scripts.
 - Ragmir does not provide an HTTP server or fixed port. A network-facing host owns transport security, authentication, authorization, and rate limits.
 - Index writers are serialized across local OS processes through a private lock under `storageDir`; do not claim a distributed or shared-network-filesystem lock.
-- Team diagnostics exchange explicit metadata-only snapshots of relative paths, checksums, readiness,
-  versions, and configuration. Never include source text or absolute project paths, choose an
-  authoritative copy, or modify peer sources during comparison.
+- Git-backed team sync treats the current branch upstream as the declared authority. Fetch only
+  that branch, fast-forward only a clean non-divergent history, then ingest incrementally. Never
+  stash, reset, rebase, create a merge commit, or delete the active index. `--no-pull` keeps branch
+  updates manual; fetch and ingest failures preserve the last valid local index when one exists.
+- Metadata-only snapshots are advanced diagnostics for exact or non-Git drift. Never include source
+  text or absolute project paths, choose an authoritative copy, or modify peer sources.
 - Package upgrades must preserve the last validated index until an incompatible replacement passes
   staged-generation validation and activates atomically. Older configs keep safe defaults; never
   require deleting `.ragmir/storage/` as the first repair step.
@@ -48,9 +51,8 @@
 - When code changes public behavior, commands, configuration, supported formats, architecture, or product claims, update the relevant docs and landing in the same change. For internal-only changes, verify both surfaces and leave them unchanged when no update is needed.
 - Lead public documentation with the value proposition, a working quick start, and the strongest
   guarantees. Move operational depth to focused guides instead of repeating it across READMEs.
-- Present team use as a positive workflow: shared sources and configuration, one local ingest per
-  developer, then a corpus-fingerprint check. Keep low-level safeguards in the team and
-  configuration guides rather than turning team collaboration into the dominant public section.
+- Present team use as one positive workflow: merge reviewed changes upstream, run `rgr team sync`,
+  receive a ready private index. Keep snapshots and low-level safeguards in focused advanced guides.
 
 ## Validation
 

CLAUDE.md

@@ -33,8 +33,8 @@ Keep the English setup prompt identical across Core, the landing, root and packa
 `docs/quick-start.md`, and the wiki. The public-surface smoke test enforces repository copies.
 Lead public documentation with the value proposition, a working quick start, and the strongest
 guarantees. Move operational depth to focused guides instead of repeating it across READMEs.
-Present team use as a positive workflow: shared sources and configuration, one local ingest per
-developer, then a corpus-fingerprint check. Keep low-level safeguards in focused guides.
+Present team use as one positive workflow: merge reviewed changes upstream, run `rgr team sync`,
+receive a ready private index. Keep snapshots and low-level safeguards in focused advanced guides.
 
 Every commit promoted to `main` that can trigger semantic-release must include these exact body
 sections with at least one bullet each: `Release highlights:`, `Release details:`, and
@@ -54,9 +54,12 @@ consumer local. Qwen and Gemma are optional Chat profiles, never Core or MCP req
 For repeated retrieval in a stateful Node.js process, use one `RagmirClient` per project root and
 close it during shutdown. Ragmir does not provide an HTTP server or fixed port; network-facing hosts
 own transport security, authentication, authorization, and rate limits.
-Team diagnostics exchange metadata-only snapshots of relative paths, checksums, readiness,
-versions, and configuration. Never include source text or absolute project paths, choose an
-authoritative copy, or modify peer sources during comparison.
+Git-backed team sync treats the current branch upstream as the declared authority. Fetch only that
+branch, fast-forward only a clean non-divergent history, then ingest incrementally. Never stash,
+reset, rebase, create a merge commit, or delete the active index. `--no-pull` keeps branch updates
+manual; fetch and ingest failures preserve the last valid local index when one exists.
+Metadata-only snapshots are advanced diagnostics for exact or non-Git drift. Never include source
+text or absolute project paths, choose an authoritative copy, or modify peer sources.
 Package upgrades preserve the last validated index until an incompatible replacement passes staged
 generation validation and activates atomically. Older configs keep safe defaults; never require
 deleting `.ragmir/storage/` as the first repair step.

README.md

@@ -40,7 +40,7 @@ Outcome: Core installed with the repository's package manager; useful sources se
 1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
 2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
 3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
-4) Solo or team use? If team, what Git/Drive/folder revision is authoritative and who may receive metadata-only snapshots?
+4) Solo or team? If team, is Git upstream authoritative, and should safe pulls be automatic or disabled with --no-pull?
 5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
 6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
 7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?
@@ -53,7 +53,7 @@ Outcome: Core installed with the repository's package manager; useful sources se
 - Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
 - For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
 - Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
-- For teams, ingest locally, create an ignored metadata-only snapshot, compare it, explain every drift, and never choose authority automatically.
+- For Git teams, run rgr team sync. It safely pulls and ingests; --no-pull keeps Git manual. Snapshots are advanced diagnostics.
 
 4. Prove the result:
 - Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
@@ -158,27 +158,25 @@ resource budgets, and monorepo routing.
 
 ```mermaid
 flowchart LR
-    A["Shared source folder"] --> B["Versioned Ragmir config"]
-    B --> C["Local ingest per developer"]
-    C --> D["Ready index"]
-    D --> E["Export team snapshot"]
-    E --> F["Compare and resolve exact drift"]
+    A["Merge into the declared upstream"] --> B["rgr team sync"]
+    B --> C["Safe Git fast-forward"]
+    C --> D["Incremental local ingest"]
+    D --> E["Ready private index"]
 ```
 
-Teams use Git, Drive, or their existing file workflow to synchronize one source of truth, commit the
-same Ragmir source globs and configuration, then build one local index per developer:
+Git-backed teams build one private index per developer and use one command after reviewed changes
+land through a merge request:
 
 ```bash
-pnpm exec rgr team snapshot --label alice --output .ragmir/team/alice.json
-pnpm exec rgr team compare .ragmir/team/alice.json --local-label christophe
+pnpm exec rgr team sync
 ```
 
-The comparison names configuration differences plus local-only, peer-only, and changed files, then
-gives ordered repair steps. It never guesses which copy is authoritative: the team keeps that
-decision in Git, Drive, or its existing source workflow. `ready` means the index can serve and be
-compared; privacy warnings are reported as non-blocking security advisories with a separate
-`rgr security-audit` action. Existing v2.19 snapshots remain comparable without reindexing.
-Detailed safeguards live in the
+Ragmir fetches the current branch upstream, fast-forwards only a clean non-divergent branch, then
+reindexes changed sources incrementally. Dirty, ahead, diverged, detached, offline, and no-upstream
+states never rewrite history and return one action. Use `--no-pull` to keep branch updates manual or
+`--check` to preview. Advanced `team snapshot` and `team compare` diagnostics remain available for
+non-Git sources or exact drift analysis, including existing v2.19 snapshots. Detailed safeguards
+live in the
 [team guide](./docs/agent-integration.md#team-knowledge-bases) and
 [configuration reference](./docs/configuration.md#stable-team-source-configuration).
 

context7.json

@@ -36,7 +36,7 @@
     "Run `rgr upgrade --check` after updating the package and before retrieval with the new runtime. `rgr upgrade` refreshes managed helpers and safely stages any required rebuild without deleting the active index first; a long-running host can cut over after status=current and ready=true. `rgr doctor --fix` uses the same repair path.",
     "Config resolves from the caller's working directory (`.ragmir/config.json`), never from the package install path.",
     "In a monorepo, the nearest configured ancestor is active; use `rgr bases --json` or explicit `--project-root` to verify routing.",
-    "Teams synchronize one source-of-truth folder with Git, Drive, or their existing file workflow, commit stable source globs and Ragmir configuration, then ingest locally per developer. Use `rgr team snapshot` and `rgr team compare` to explain version, configuration, local-only, peer-only, and changed-file drift without source text. Ragmir never chooses the authoritative copy; keep actively written .ragmir/storage directories local to each workstation.",
+    "Git-backed teams run `rgr team sync`: Ragmir fetches the current branch upstream, applies only a clean non-divergent fast-forward, then refreshes the private local index. `--no-pull` disables branch updates and `--check` previews. Dirty, ahead, diverged, detached, offline, and no-upstream states never rewrite history. Advanced snapshots remain available for exact or non-Git drift diagnostics; keep actively written .ragmir/storage directories local to each workstation.",
     "Use `rgr preview` to inspect redacted chunks without writing an index, and `search(..., { explain: true })` only when rank diagnostics are needed.",
     "Explained searches expose a ranking-policy fingerprint, deterministic vector and lexical contributions, FTS or complete-fallback activation and reason, candidate budgets, and lexical coverage; truncated fallback scans are rejected.",
     "The bounded primary FTS pool uses structural context and body text. Exact file paths use a bounded scalar variant. Controlled phrase, identifier, and rare-term queries expand only an insufficient primary pool. Diversification selects distinct sources first, then backfills ranked non-duplicate, non-overlapping chunks to topK.",

docs/agent-integration.md

@@ -66,54 +66,83 @@ from different bases labeled rather than silently merging citations.
 
 ## Team knowledge bases
 
-Ragmir keeps one local index per developer. Synchronize one source-of-truth folder with Git, Drive,
-or a team script, and keep the Ragmir version and tracked configuration aligned.
+Ragmir keeps one private local index per developer. For a Git-backed team, check out the branch the
+team declared authoritative, configure its upstream once, then use one command:
 
-On one workstation, export a metadata-only snapshot under ignored local state:
+```bash
+rgr team sync
+```
+
+The command fetches only that upstream branch, compares Git history, and fast-forwards the checked
+out branch only when the worktree is clean, the local branch has no unpublished commit, and history
+has not diverged. It then runs incremental ingestion and reports `current`, `updated`, or one clear
+action. It never stashes, resets, rebases, creates a merge commit, deletes the active index, or
+chooses another branch.
+
+This keeps the normal team loop small:
+
+1. A developer pushes a branch and opens or updates the merge request.
+2. The team reviews and merges it into the declared upstream branch.
+3. Other developers run `rgr team sync`; safe updates and local reindexing happen together.
+
+Use `--no-pull` to fetch and compare while keeping branch updates manual. Use `--check` to preview
+without changing the worktree or index, `--no-fetch` for an explicitly offline run, `--strict` in
+CI, and `--json` for automation. A dirty, ahead, diverged, detached, or untracked branch is never
+rewritten. A failed fetch keeps the last valid local index available and reports that upstream
+freshness is unverified. A failed ingestion keeps the previous validated index instead of deleting
+it first.
+
+The ignored `.ragmir/config.json` remains local. If every workstation needs the exact same source
+contract, version a reviewed template in the repository and apply it during setup. `rgr team sync`
+synchronizes tracked sources through Git; it does not commit or distribute private Ragmir state.
+
+### Advanced drift diagnostics
+
+Snapshots remain available for a non-Git authority such as Drive, or when the team needs an exact
+configuration and per-file comparison. They are not part of the normal Git workflow. On one
+authorized workstation:
 
 ```bash
-rgr team snapshot --label alice --output .ragmir/team/alice.json
+rgr team snapshot --label local --output .ragmir/team/local.json
 ```
 
 Share that file only with teammates authorized for the corpus. It contains relative paths,
 SHA-256 checksums, readiness, version, and index settings, never source text or an absolute project
 path. On another workstation:
 
 ```bash
-rgr team compare .ragmir/team/alice.json --local-label christophe
+rgr team compare .ragmir/team/local.json --local-label peer
 ```
 
 The result distinguishes configuration drift, local-only files, peer-only files, and changed files.
-It provides ordered commands for readiness, upgrade, ingestion, or rebuild work. Ragmir never
-chooses which copy is correct; use the declared Git commit, Drive revision, or team folder as the
-authority, synchronize it, ingest again, then compare fresh snapshots until
+It provides ordered commands for readiness, upgrade, ingestion, or rebuild work. Use the declared
+Drive revision, team folder, or Git commit as the authority, then compare fresh snapshots until
 `status=synchronized`. Operational readiness and privacy review are independent: a matching index
 with local extractor or permission warnings remains synchronized, while the comparison exposes
 per-side security advisory counts and recommends `rgr security-audit`. Do not rebuild a healthy
-index only to clear an advisory. Existing v2.19 snapshots are interpreted from their stored health
-metadata, so teammates can upgrade at different times without regenerating them first.
+index only to clear an advisory. Existing v2.19 snapshots remain compatible.
 
-Version stable directory or glob contracts instead of rewriting a tracked config with the files
-found on the current machine. The lower-level `corpusFingerprint` returned by `rgr status --json`,
-`status()`, or `ragmir_status` remains useful for a quick equality check. Matching values prove the
-same indexed relative paths and source bytes only when both reports are ready with no missing or
-stale files. Use `rgr team compare` when values differ and the team needs the exact cause.
+Use stable directory or glob contracts instead of rewriting local config from files found on one
+machine. The lower-level `corpusFingerprint` returned by `rgr status --json`, `status()`, or
+`ragmir_status` remains useful for a quick equality check. Matching values prove the same indexed
+relative paths and source bytes only when both reports are ready with no missing or stale files.
+Use `rgr team compare` only when values differ and the team needs the exact cause.
 
 Use `sourceFingerprintMode: "strict"` when a synchronization tool can preserve file metadata while
 replacing its content. Older manifests return a `null` fingerprint until the next successful
 ingestion.
 
 Do not synchronize `.ragmir/storage/` between active writers. A team bootstrap can call
-`initProject`, `addSourceEntries`, and `createRagmirClient`, but the application or sync tool remains
-responsible for distributing the source files.
+`initProject`, `addSourceEntries`, and `syncTeamKnowledge`; each workstation still owns its index.
 
 ### Agent behavior on team drift
 
-An agent using the bundled Ragmir skill should check readiness before relying on retrieval. When a
-peer snapshot is available, it should run the comparison and warn the user in the user's language
-when `status` is not `synchronized`. It should summarize the exact drift and suggested commands,
-never silently pick a winner or overwrite source files. It should describe security advisories as
-separate, non-blocking follow-ups when the operational indexes already match.
+An agent using the bundled Ragmir skill should run `rgr team sync --json` before relying on a
+Git-backed shared knowledge base. When `synchronized` is false, it should warn the user in the
+user's language, present the first recommended action, and continue only with an explicit note when
+the last valid local index may be older than upstream. It must never resolve Git history, stash,
+reset, rebase, or overwrite source files. Snapshot comparison remains the advanced fallback for an
+authorized non-Git source or exact drift investigation.
 
 ## MCP tools