Backport the check-then-fetch-or-create nuance into README/MANUAL docs

The last skill clarification (check the shared index store on every
run; fetch if it exists; a write-access user's run creates it there
the first time it's empty) hadn't been reflected in the user-facing
docs, which only described the steady-state case. Also documents the
optional index.ref field, mentioned in the skill schema but missing
from all four docs' examples.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

MANUAL.md

@@ -92,7 +92,11 @@ which stay entirely read-only. There are three ways to mount one:
   - **You don't have to build the index yourself.** `source.yaml` can add
     an `index:` block pointing at an already-built index — a git repo, or
     a shared resource — so you just fetch what someone else already
-    indexed instead of scanning the live source yourself.
+    indexed instead of scanning the live source yourself. Every run checks
+    that location first: if there's already an index there, you get it; if
+    there isn't yet (the normal state before anyone's run this with write
+    access), that's not an error — whoever has write access is the one
+    whose next run creates and publishes it there for the first time.
   - **Building/refreshing is opt-in per person, per source.** By default,
     everyone is read-only for a connector source — nobody's agent will
     scan the live connector on their behalf unless they've explicitly said
@@ -492,14 +496,22 @@ adds an `index:` block to the shared `source.yaml`:
 index:
   store: git
   location: "https://github.com/finance-team/index-cache.git"
+  # ref: main   — optional: pin a branch, tag, or subpath within that store
 ```
 
-Now, whenever *anyone* says "index external sources," the agent first
-fetches whatever's already published there — read-only users stop right
-there; the admin also rebuilds from the live connector and pushes the
-refreshed index back to that same location, so the next person's fetch
-picks it up. Leave the `index:` block out entirely (the simplest setup,
-and the right default for a single small team) and the index just lives
+The very first time anyone runs "index external sources" after that block
+is added, `https://github.com/finance-team/index-cache.git` is empty —
+that's expected, not an error. Every run checks it first: read-only users
+just see "nothing published yet, ask the admin"; the admin's run is what
+actually creates it there, since a write-access run always rebuilds from
+the live connector and pushes the result to that location, whether or not
+anything was there before. From then on, whenever *anyone* says "index
+external sources," the agent first fetches whatever's already published
+there — read-only users stop right there; the admin also rebuilds from the
+live connector and pushes the refreshed index back to that same location,
+so the next person's fetch picks it up. Leave the `index:` block out
+entirely (the simplest setup, and the right default for a single small
+team) and the index just lives
 directly inside `libs/finance-reports/` in this KB's own repo, shared the
 normal way via "sync changes" — exactly like the plain example above.
 

MANUAL.pl.md

@@ -96,6 +96,11 @@ podpięcia:
     `index:` wskazujący na już zbudowany indeks — repozytorium git albo
     zasób współdzielony — dzięki czemu po prostu pobierasz to, co ktoś
     inny już zaindeksował, zamiast samodzielnie skanować żywe źródło.
+    Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już
+    tam jest, dostajesz go; jeśli go tam jeszcze nie ma (normalny stan,
+    zanim ktokolwiek z dostępem do zapisu to uruchomił), to nie błąd —
+    ten, kto ma dostęp do zapisu, tworzy go tam i publikuje przy swoim
+    kolejnym uruchomieniu.
   - **Budowanie/odświeżanie jest opcjonalne, per osoba, per źródło.**
     Domyślnie każdy jest tylko-do-odczytu dla źródła typu konektor —
     agent nikogo nie przeskanuje żywego konektora w jego imieniu, jeśli
@@ -516,9 +521,18 @@ dodaje blok `index:` do współdzielonego `source.yaml`:
 index:
   store: git
   location: "https://github.com/finance-team/index-cache.git"
+  # ref: main   — opcjonalnie: przypina branch, tag albo podścieżkę w tym miejscu
 ```
 
-Teraz, kiedy *ktokolwiek* powie „index external sources”, agent najpierw
+Za pierwszym razem, gdy ktokolwiek uruchomi „index external sources” po
+dodaniu tego bloku, `https://github.com/finance-team/index-cache.git` jest
+puste — to oczekiwane, nie błąd. Każde uruchomienie sprawdza je najpierw:
+użytkownicy tylko-do-odczytu zobaczą po prostu „nic jeszcze nie
+opublikowano, zapytaj administratora”; to uruchomienie administratora
+faktycznie je tworzy, ponieważ uruchomienie z dostępem do zapisu zawsze
+przebudowuje indeks z żywego konektora i wypycha wynik do tej lokalizacji,
+niezależnie od tego, czy coś tam wcześniej było. Od tego momentu, kiedy
+*ktokolwiek* powie „index external sources”, agent najpierw
 pobiera to, co już zostało opublikowane — użytkownicy tylko-do-odczytu
 zatrzymują się w tym miejscu; administrator dodatkowo przebudowuje indeks
 z żywego konektora i wypycha odświeżoną wersję do tej samej lokalizacji,

README.md

@@ -156,13 +156,18 @@ Two refinements on top of that:
 - **Shared, pre-built indexes.** `source.yaml` can add an optional `index:`
   block declaring *where the already-built index lives* — a git repo, or a
   shared resource such as a network path or another connector-reachable
-  location — so most people just fetch what's already there instead of
-  building it themselves:
+  location:
   ```yaml
   index:
     store: git   # git | shared
     location: "https://github.com/org/finance-index-cache.git"
+    ref: main    # optional — branch, tag, or subpath hint within that store
   ```
+  Every run checks that location: if it already has an index, fetch it —
+  most people just read what's already there instead of building it
+  themselves. If it doesn't yet, that's the normal first-time state, not an
+  error: a write-access user's very next run is what creates and publishes
+  it there, with no separate "initialize" step.
 - **Read vs. write, per user, per source.** Whether *this* user can
   actually rebuild an index (versus only read a fetched/published one) is a
   separate, local, gitignored `libs/<name>/source.local.yaml` — read-only

README.pl.md

@@ -169,14 +169,19 @@ Dwa rozszerzenia na tym fundamencie:
 - **Współdzielone, wcześniej zbudowane indeksy.** `source.yaml` może
   dodać opcjonalny blok `index:`, który deklaruje, *gdzie już zbudowany
   indeks się znajduje* — repozytorium git albo zasób współdzielony, np.
-  ścieżka sieciowa lub inna lokalizacja dostępna przez konektor — dzięki
-  czemu większość osób po prostu pobiera to, co już jest, zamiast budować
-  to samodzielnie:
+  ścieżka sieciowa lub inna lokalizacja dostępna przez konektor:
   ```yaml
   index:
     store: git   # git | shared
     location: "https://github.com/org/finance-index-cache.git"
+    ref: main    # opcjonalnie — branch, tag albo podpowiedź co do podścieżki w tym miejscu
   ```
+  Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już
+  tam jest, zostaje pobrany — większość osób po prostu czyta to, co już
+  jest, zamiast budować to samodzielnie. Jeśli go tam jeszcze nie ma, to
+  normalny stan przy pierwszym uruchomieniu, a nie błąd: kolejne
+  uruchomienie użytkownika z dostępem do zapisu jest tym, które go tam
+  tworzy i publikuje — bez osobnego kroku „inicjalizacji".
 - **Odczyt vs. zapis, per użytkownik, per źródło.** Czy *ten* użytkownik
   może faktycznie przebudować indeks (a nie tylko czytać pobraną/
   opublikowaną wersję) to odrębne, lokalne, ignorowane przez git