docs(team): simplify shared knowledge sync (#152) (#154)

Release highlights:
- make private team knowledge refresh understandable in one safe Git workflow

Release details:
- Documentation: focus normal sync on reviewed upstream changes and one command
- Documentation: move snapshots and MCP internals behind advanced disclosure
- Reliability: give slow Git-and-index fixtures the existing 15-second test budget

Verification:
- pnpm validate
- GitNexus detects low-risk documentation and test changes

Author: jb-thery

CONTRIBUTING.md

@@ -30,8 +30,8 @@ pnpm bootstrap
 ```
 
 `pnpm bootstrap` runs `mise install && pnpm install`. Without mise, install the Node.js 22 release
-pinned in `mise.toml` and pnpm, then run `pnpm install` directly. Published packages retain their
-documented Node.js 20 runtime support; the repository toolchain itself requires Node.js 22.
+pinned in `mise.toml` and pnpm, then run `pnpm install` directly. The published packages and the
+repository toolchain require Node.js 22 or later.
 
 Activate mise in your shell (`mise activate`, per the
 [mise docs](https://mise.jdx.dev/getting-started.html)) so that entering this repository puts the

README.md

@@ -164,19 +164,21 @@ flowchart LR
     D --> E["Ready private index"]
 ```
 
-Git-backed teams build one private index per developer and use one command after reviewed changes
-land through a merge request:
+Git-backed teams build one private index per developer. The current branch upstream is the only
+declared authority: Git carries the reviewed change, Ragmir refreshes the local evidence.
 
 ```bash
 pnpm exec rgr team sync
 ```
 
-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
+1. Open and review a pull request (or merge request).
+2. Merge it into the declared upstream.
+3. Run `rgr team sync` on each workstation that needs fresh evidence.
+
+Ragmir fast-forwards only a clean non-divergent branch and reindexes changed sources incrementally.
+Otherwise it leaves history and the valid index alone, then returns one action. `--no-pull` keeps
+branch updates manual and `--check` previews. Snapshots are an advanced fallback 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).
 

docs/agent-integration.md

@@ -66,41 +66,69 @@ from different bases labeled rather than silently merging citations.
 
 ## Team knowledge bases
 
-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:
+Ragmir keeps one private local index per developer. For a Git-backed team, the current branch
+upstream is the only declared authority. Configure it once, then use one command:
 
 ```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.
+### The everyday workflow
 
-This keeps the normal team loop small:
+```mermaid
+flowchart LR
+    A["Push a reviewable change"] --> B["Merge to the declared upstream"]
+    B --> C["rgr team sync"]
+    C --> D["Safe fast-forward, if possible"]
+    D --> E["Incremental local ingest"]
+    E --> F["Ready private index"]
+```
 
-1. A developer pushes a branch and opens or updates the merge request.
+1. A developer pushes a branch and opens or updates a pull request (or 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.
+3. Other developers run `rgr team sync`; source updates and local reindexing happen together.
+
+Git already shows what changed and where review is needed. Ragmir does not add labels, snapshots,
+or another source of truth to this normal path.
+
+| Result | What Ragmir does |
+| --- | --- |
+| `current` | Keeps the checked-out sources and local index because they are already aligned. |
+| `updated` | Fetches only the declared upstream, fast-forwards safely, then ingests changed sources. |
+| Needs action | Leaves Git history and the active index untouched, then explains the first next step. |
+
+The automatic path fetches only that upstream and fast-forwards only when the worktree is clean,
+the local branch has no unpublished commits, and history has not diverged. It never stashes, resets,
+rebases, creates a merge commit, chooses another branch, or deletes the active index.
+
+### Choose the sync mode
+
+| Need | Command | Effect |
+| --- | --- | --- |
+| Normal team update | `rgr team sync` | Safely update from upstream and ingest incrementally. |
+| Keep Git updates manual | `rgr team sync --no-pull` | Fetch and compare, but do not change the checked-out branch. |
+| Preview only | `rgr team sync --check` | Report Git and index state without changing either one. |
+| Work offline | `rgr team sync --no-fetch` | Use cached Git state and local sources only. |
+| Enforce in automation | `rgr team sync --strict --json` | Return a typed report and fail unless freshness and readiness are proven. |
 
-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.
+Dirty, ahead, diverged, detached, untracked, or no-upstream branches are never rewritten. A failed
+fetch keeps the last valid index and marks upstream freshness as unverified. A failed ingestion also
+preserves the previous validated index. Resolve the Git state through the normal pull-request or
+merge-request workflow, then run the same command again.
 
 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
+### When exact drift diagnosis is genuinely needed
+
+Snapshots are an advanced fallback for a non-Git authority, such as Drive, or for a specific
+configuration and per-file investigation. They are not a prerequisite for ordinary Git teams.
 
-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:
+<details>
+<summary>Compare two authorized snapshots without sharing source text</summary>
+
+On one authorized workstation:
 
 ```bash
 rgr team snapshot --label local --output .ragmir/team/local.json
@@ -135,6 +163,8 @@ ingestion.
 Do not synchronize `.ragmir/storage/` between active writers. A team bootstrap can call
 `initProject`, `addSourceEntries`, and `syncTeamKnowledge`; each workstation still owns its index.
 
+</details>
+
 ### Agent behavior on team drift
 
 An agent using the bundled Ragmir skill should run `rgr team sync --json` before relying on a
@@ -144,7 +174,7 @@ the last valid local index may be older than upstream. It must never resolve Git
 reset, rebase, or overwrite source files. Snapshot comparison remains the advanced fallback for an
 authorized non-Git source or exact drift investigation.
 
-## MCP tools
+## Use Ragmir through MCP
 
 The server exposes `ragmir_status`, `ragmir_route_prompt`, `ragmir_search`, `ragmir_ask`,
 `ragmir_research`, `ragmir_expand`, `ragmir_audit`, `ragmir_evaluate`, `ragmir_usage_report`, and
@@ -164,6 +194,8 @@ The TypeScript `sources({ offset, limit })` method can request later pages direc
 manifest file snapshot without materializing the complete source list; its default page remains 50
 files.
 
+### Retrieve bounded evidence
+
 Use compact retrieval first, then pass a returned citation to `ragmir_expand` when the agent needs
 the exact chunk or a bounded neighbor window. Search, ask, research, expansion, audit, and evaluation
 accept `maxBytes`. Variable-size tool and resource JSON is bounded by `mcpMaxOutputBytes` and an
@@ -177,6 +209,9 @@ size, audit detail, and returned evaluation case details, while keeping aggregat
 `ragmir_ask` returns cited evidence, not a model generated answer. A cloud agent can receive returned
 passages, so choose that handoff only when it matches the corpus's confidentiality requirements.
 
+<details>
+<summary>Advanced: response contracts, safety annotations, and server lifecycle</summary>
+
 Every tool advertises non-destructive behavior to compatible clients. Search, ask, research, and
 evaluation conservatively advertise open-world behavior because explicitly enabled semantic models
 may download public weights. The pure prompt router, security audit, and usage report also advertise
@@ -202,6 +237,8 @@ before and after the call. Ragmir does not open an HTTP port; applications that
 transport own its authentication and
 authorization boundary.
 
+</details>
+
 ## Verify
 
 ```bash

docs/cli-reference.md

@@ -83,23 +83,36 @@ report records both configured and consumed budgets.
 rgr team sync
 ```
 
-`team sync` treats the current branch upstream as the declared source of truth. It fetches that
-single branch, fast-forwards only a clean branch with no local-only commits or divergence, then runs
-incremental ingestion. Git authentication is non-interactive and each Git command is bounded. A
-dirty, ahead, diverged, detached, or no-upstream state never changes branch history and returns one
-recommended action. Fetch and ingestion failures keep the previous valid local index available
-when one exists.
+Use this after reviewed source changes merge into the current branch upstream. That upstream is the
+declared authority, and Git remains the place where the team reviews differences. `team sync`
+fetches only that branch, fast-forwards only a clean non-divergent history with no local-only
+commits, then ingests changed sources incrementally. Git authentication is non-interactive and each
+Git command is bounded.
+
+| Result | Meaning |
+| --- | --- |
+| `current` | The checked-out sources and private local index already match upstream. |
+| `updated` | A safe fast-forward and incremental ingest completed. |
+| Needs action | Git history and the active index were preserved; follow the one recommended action. |
 
 | Option | Behavior |
 | --- | --- |
-| `--no-pull` | Fetch and compare, but never update the checked-out branch. |
+| `--no-pull` | Fetch and compare, but keep branch updates manual. |
 | `--no-fetch` | Avoid network access and use only cached Git state plus local sources. |
 | `--check` | Fetch and report without changing the worktree or index. |
 | `--git-timeout-ms N` | Bound each Git command, from 1 ms to 300,000 ms. |
 | `--strict` | Exit with code 1 unless upstream freshness and local index readiness are proven. |
 | `--json` | Return the complete typed report. |
 
-Snapshots are an advanced fallback for non-Git sources or exact drift investigation:
+A dirty, ahead, diverged, detached, or no-upstream state never rewrites history. Fetch and ingestion
+failures preserve the previous valid local index when one exists. Resolve the Git state through the
+normal pull-request or merge-request workflow, then rerun the same command.
+
+<details>
+<summary>Advanced: diagnose exact drift or a non-Git authority</summary>
+
+Snapshots are not part of the normal Git workflow. Use them for a non-Git authority or a specific
+per-file comparison:
 
 ```bash
 rgr team snapshot --label local --output .ragmir/team/local.json
@@ -120,6 +133,8 @@ do not require deleting or rebuilding the index. Snapshots written by Ragmir v2.
 v2.19.2 remain compatible. These advanced commands never change source files or decide which side
 is authoritative.
 
+</details>
+
 ## Safe upgrades
 
 ```bash

docs/troubleshooting.md

@@ -76,7 +76,8 @@ updates must remain manual and `--check` for a no-worktree-change preview.
 
 The active `.ragmir/config.json` is intentionally local and ignored. If results still differ after
 Git is current, verify that both workstations use the same reviewed source-contract template and
-Ragmir version. For an exact diagnosis or a non-Git authority, use the advanced snapshot flow:
+Ragmir version. Do not start with snapshots: use them only for an exact diagnosis or a non-Git
+authority:
 
 ```bash
 rgr team snapshot --label local --output .ragmir/team/local.json

packages/ragmir-core/src/team-sync.test.ts

@@ -79,7 +79,7 @@ describe.sequential("team sync", () => {
     expect(await readFile(path.join(fixture.local, "docs", "decision.md"), "utf8")).toBe(
       "Local draft.\n",
     )
-  })
+  }, 15_000)
 
   it("should require the merge-request workflow when local and upstream histories diverge", async () => {
     const fixture = await createGitFixture()
@@ -153,7 +153,7 @@ describe.sequential("team sync", () => {
       "Check mode did not change the worktree or refresh the index.",
     )
     expect(await git(fixture.local, ["rev-parse", "HEAD"])).toBe(headBefore)
-  })
+  }, 15_000)
 
   it("should avoid remote access and branch updates when fetch is disabled", async () => {
     const fixture = await createGitFixture()