From f3dbce732779e5b5a1fad391552a3dda86d6857e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Tue, 21 Jul 2026 08:41:14 +0200 Subject: [PATCH] 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 --- MANUAL.md | 26 +++++++++++++++++++------- MANUAL.pl.md | 16 +++++++++++++++- README.md | 9 +++++++-- README.pl.md | 11 ++++++++--- 4 files changed, 49 insertions(+), 13 deletions(-) diff --git a/MANUAL.md b/MANUAL.md index 31e366d..115c223 100644 --- a/MANUAL.md +++ b/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. diff --git a/MANUAL.pl.md b/MANUAL.pl.md index 837d376..9447120 100644 --- a/MANUAL.pl.md +++ b/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, diff --git a/README.md b/README.md index e7026c4..5d49195 100644 --- a/README.md +++ b/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//source.local.yaml` — read-only diff --git a/README.pl.md b/README.pl.md index 3e3d7e5..9b624b8 100644 --- a/README.pl.md +++ b/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