From 412364bf74baac58d65e194c147f74a801c4bd66 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 10:52:57 +0200 Subject: [PATCH 01/19] =?UTF-8?q?docs(sl):=20translate=20wiki=20batch=201?= =?UTF-8?q?=20=E2=80=94=207=20core=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mother-hive (matični hive): forced-command SSH, single home, peer auth, key-on-seed, daemon user - task-board (tabla opravil): capability scoring, cron/interval/once, intake drain, SQLite backing - operator-attention (operaterska pozornost): attention bar, jump/filter keys, edge-triggered alerts, NO_COLOR pitfall - contracts (JSON pogodbe): stable schemas, golden tests, evolution rules - cost-model (model stroškov): cache-hit metering, fast/smart/max, T14 compaction, DeepSeek probe - layered-soul (plastovita duša): import path, deferred stores, one-way direction - index (wiki kazalo): conventions, lint workflow, full page table Commands/JSON/code paths kept in English; prose + frontmatter translated. --- docs/wiki/sl/contracts.md | 53 +++++++++++ docs/wiki/sl/cost-model.md | 97 +++++++++++++++++++ docs/wiki/sl/index.md | 75 +++++++++++++++ docs/wiki/sl/layered-soul.md | 55 +++++++++++ docs/wiki/sl/mother-hive.md | 119 +++++++++++++++++++++++ docs/wiki/sl/operator-attention.md | 146 +++++++++++++++++++++++++++++ docs/wiki/sl/task-board.md | 101 ++++++++++++++++++++ 7 files changed, 646 insertions(+) create mode 100644 docs/wiki/sl/contracts.md create mode 100644 docs/wiki/sl/cost-model.md create mode 100644 docs/wiki/sl/index.md create mode 100644 docs/wiki/sl/layered-soul.md create mode 100644 docs/wiki/sl/mother-hive.md create mode 100644 docs/wiki/sl/operator-attention.md create mode 100644 docs/wiki/sl/task-board.md diff --git a/docs/wiki/sl/contracts.md b/docs/wiki/sl/contracts.md new file mode 100644 index 0000000..092d77f --- /dev/null +++ b/docs/wiki/sl/contracts.md @@ -0,0 +1,53 @@ +--- +title: Stabilne JSON pogodbe +description: Jezikovno neodvisne oblike na žici, v skupni rabi med Colibri (Rust) in Clawdie agenti (TypeScript). +--- + +← [kazalo](./index.md) + +`colibri-contracts` hrani stabilne, jezikovno neodvisne oblike na žici, v +skupni rabi med Colibri (Rust) in Clawdie agenti (TypeScript). Lasti si +_sheme in (De)serialize_, ne poslovne logike. + +## Zakaj ločen pogodbeni zaboj + +- Preprečuje podvojene definicije med stezama Rust in TypeScript. +- Ohranja potrjene manifeste v `manifests/`, ki so razčlenljivi na obeh + straneh. +- Centralizira nize shem, vzdevke za preimenovanje polj in privzetke za + povratno združljivost. + +## Aktivne sheme + +| Shema | Rust struct | Namen | +| -------------------------------------- | --------------------- | ------------------------------------------------------------------------- | +| `clawdie.interagent.run-manifest.v1` | `RunManifest` | Beleži tek gradnje/testa — vloga, agent, artefakti, povzetek. | +| `clawdie.runtime-version-inventory.v1` | `RuntimeInventory` | Posnetek izvajalnega okolja gostitelja — OS, različice paketov, npm/node. | +| `clawdie.provider-smoke.result.v1` | `ProviderSmokeResult` | Rezultat sonde predpomnilnika DeepSeek in obračun žetonov. | + +Konstante shem in strukture živijo v `crates/colibri-contracts/src/lib.rs`. + +## Pravila razvoja + +- Zaboj ne nosi **nobene logike** — samo `serde` strukture in konstante shem. +- Nova polja so običajno neobvezna z `#[serde(default)]`, da se stari + manifesti še vedno razčlenijo. +- `RuntimeInventory.pi` je neobvezen, ker vsak gostitelj ne namesti `pi` ali + `zot`. +- `HostStatus.raw` je lovilna vrednost `serde_json::Value`, da se lahko + zajame izhod sovražnega zbiralnika brez prisile v dvig sheme. + +## Zlati testi + +`crates/colibri-contracts/tests/golden.rs` razčleni vsak potrjen manifest v +`manifests/` in preveri enakost povratnega zapisa. Primerki so namenjeni +**medplatformni** rabi — če se manifest, ustvarjen na Linuxu, razlikuje od +tistega na FreeBSD 15, je treba razliko razumeti in dokumentirati, preden se +združi. + +## Glej tudi + +- [cost-model](./cost-model.md) — kako rezultat sonde ponudnika hrani merjenje + predpomnilnika. +- [runtime-inventory](./runtime-inventory.md) — kje se ustvari popis + izvajalnega okolja. diff --git a/docs/wiki/sl/cost-model.md b/docs/wiki/sl/cost-model.md new file mode 100644 index 0000000..17641c6 --- /dev/null +++ b/docs/wiki/sl/cost-model.md @@ -0,0 +1,97 @@ +--- +title: Model stroškov +description: Kako Colibri sledi vsakemu žetonu, meri zadetke predpomnilnika in samodejno stopnjuje med cenovnimi načini. +--- + +← [kazalo](./index.md) + +## Kaj je to + +Colibri sledi vsakemu žetonu, ki gre skozi agentsko sejo, in meri stroške +glede na nastavljiv proračun. Ključni vpogled: **žetoni zadetka predpomnilnika +stanejo 10× manj** kot sveži žetoni pri DeepSeek — zato je predpona poziva +načrtovana tako, da je bajtno stabilna med zahtevami, kar maksimira zadetke +predpomnilnika. Trije cenovni načini (fast, smart, max) predstavljajo različne +točke na kompromisu hitrost/strošek, model pa samodejno stopnjuje, ko cenejši +način ne zmore več. + +## Odločitve + +### Bajtno stabilna predpona poziva → merjenje zadetkov predpomnilnika + +Sistemski poziv in zgodnji bloki konteksta so **bajt-za-bajtom enaki** med +zaporednimi zahtevami na isto končno točko DeepSeek. Cene zadetkov +predpomnilnika DeepSeek jih znižajo za ~90%. Colibrijeva sonda +`colibri-deepseek` določi natančno razdelitev števila žetonov med predpomnjenimi +in svežimi žetoni na zahtevo, sledilec stroškov pa zabeleži oboje, tako da +proračun seje odraža **dejanske** znižane stroške, ne nominalnega števila +žetonov. + +**Zakaj ne preprosto šteti žetonov**: štetje žetonov z offline tokenizatorjem +da zgornjo mejo, ne pa resničnih stroškov. API DeepSeek včasih ponovno +predpomni in včasih ne — sonda izmeri, kaj se je dejansko zgodilo. Popust je +prevelik (10×), da bi ostal neizmerjen. + +→ [headroom-sidecar](./headroom-sidecar.md), +[`COLIBRI-TOKENOMICS-TRIFECTA.md`](../COLIBRI-TOKENOMICS-TRIFECTA.md), +[`crates/colibri-deepseek/src/lib.rs`](../../crates/colibri-deepseek/src/lib.rs) + +### Trije cenovni načini (fast → smart → max) + +| Način | Proračun (žetoni) | Obnašanje | +| ----- | ----------------- | ---------------------------------------------------------------------------------------- | +| Fast | 16K | Največ zadetkov predpomnilnika, najmanj svežih žetonov. Zgodaj zavrne velike razširitve. | +| Smart | 64K | Privzeto. Uravnoteži ponovno uporabo predpomnilnika s prostorom za nadaljnje korake. | +| Max | 256K | Skoraj nikoli ne doseže proračuna. Za enkratne globoke naloge, kjer je strošek drugoten. | + +Demon **samodejno stopnjuje**, ko seja izčrpa svoj proračun v nižjem načinu: +fast → smart → max. Stopnjevanje je enosmerno (nikoli ne zniža sredi seje). + +**Zakaj trije načini, ne zvezni drsnik**: tukaj zmaga preprostost. Tri dobro +razumljene točke pokrijejo prostor — operaterji izbirajo po apetitu tveganja, +ne po finem uglaševanju številke. Veriga stopnjevanja pomeni "začni poceni, +plačaj več samo, če deluje". + +→ [`COLIBRI-TOKENOMICS-TRIFECTA.md`](../COLIBRI-TOKENOMICS-TRIFECTA.md), +[`crates/colibri-daemon/src/cost.rs`](../../crates/colibri-daemon/src/cost.rs) + +### Stiskanje T14 (obrezovanje proračuna, ne krajšanje) + +Ko seja skoraj preseže svoj proračun, Colibri stisne rezultate orodij v +nestanovitnem območju — pošlje jih skozi stranski vagon headroom v povzetek, +nato obreže najstarejše nestanovitne bloke, dokler poziv ne sodi v proračun. +**Predpona** (sistemski poziv, statični kontekst) ni nikoli obrezana — samo +nestanovitna pripona. + +Če stiskanje ne zadostuje in je samodejno stopnjevanje omogočeno, način +prestopi navzgor, preden pride do krajšanja. + +**Zakaj ne preprosto krajšati**: krajšanje sredi pogovora izgubi kontekst, ki +ga agent potrebuje za nadaljevanje. Stiskanje ohrani pomensko vsebino ob +nižjih stroških žetonov. Stranski vagon headroom je neobvezen (privzeto +izklopljen); brez njega je zasilni izhod preprosto krajšanje. + +→ [headroom-sidecar](./headroom-sidecar.md), +[`crates/colibri-daemon/src/session.rs`](../../crates/colibri-daemon/src/session.rs) + +### Sonda zadetka predpomnilnika (specifična za DeepSeek) + +Zaboj `colibri-deepseek` pošlje predpoletno zahtevo z znanim pozivom na API +DeepSeek in razčleni glave odgovora, da določi razdelitev zadetkov +predpomnilnika (prompt_cache_hit_tokens / prompt_cache_miss_tokens). To je +specifično za ponudnika — DeepSeek je edini ponudnik, ki izpostavlja to +natančnost. Sonda teče enkrat na spremembo konfiguracije seje, ne na vsako +zahtevo. + +**Zakaj sonda in ne kljuka**: vmesna programska oprema, ki prestreza vsak +odgovor API, bi povezala sledenje stroškov s plastjo HTTP. Sonda to loči — +sledilec stroškov vpraša "kakšno je bilo razmerje predpomnilnika?" in sonda +odgovori, neodvisno od tega, kako je bila zahteva izvedena. + +→ [`crates/colibri-deepseek/src/lib.rs`](../../crates/colibri-deepseek/src/lib.rs) + +## Glej tudi + +- [task-board](./task-board.md) — razporejevalnik, ki razpošilja opravila znotraj proračunov sej +- [mother-hive](./mother-hive.md) — arhitektura MCP (druga stroškovna domena) +- [quality-gates](./quality-gates.md) — vrata, ki preverjajo razčlenjevanje cenovnih načinov diff --git a/docs/wiki/sl/index.md b/docs/wiki/sl/index.md new file mode 100644 index 0000000..6e006d2 --- /dev/null +++ b/docs/wiki/sl/index.md @@ -0,0 +1,75 @@ +--- +title: Colibri Wiki +description: Zbirka znanja o odločitvah in arhitekturi Colibri — utemeljitve, ki jih koda ne more izraziti. +--- + +Zbirka znanja o Colibrijevih **odločitvah in arhitekturi** — po vzoru +[vzorca LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) +Andreja Karpathyja. + +Vsak večji podsistem ima stran, ki beleži **zakaj** je bil zgrajen tako, kot +je — utemeljitve, ki jih koda ne more izraziti. Izvedbena dokumentacija v +`docs/` pokriva _kako_; te strani pokrivajo _zakaj_. + +## Zakaj to obstaja + +Zastarele odločitve se kopičijo hitreje, kot jih kdorkoli ročno pregleda: +preimenovanje, ki je bilo samo napol uporabljeno, dokument, ki še vedno +opisuje staro zasnovo, privzetek, ki je ostal od presežene izbire. Več +nedavnih prehodov je bilo porabljenih prav za iskanje tega (`pi → zot`, +`usb_nodes → hive_nodes`, podedovano preimenovanje v `sample`). Ta wiki naredi +knjigovodstvo skoraj brezstroškovno: eno mesto, ki beleži _kaj je bilo +odločeno_, povezuje na _kje v kodi živi_ in ga je mogoče **lintati** za odmik. + +## Konvencije (shema) + +Ta pravila ohranjajo wiki kot vzdržljiv artefakt, ne kot drugi vir resnice: + +1. **Koda je vir resnice.** Strani opisujejo _odločitve_ in _kje_ živijo; + povezujejo na kodo/dokumentacijo, namesto da bi ponovno razlagale izvedbo. + Ko je odločitev dostavljena, skrči stran na "kako deluje + povezava." +2. **Povezuj, ne podvajaj.** Sklicevanje na kodo kot `pot/do/datoteke.rs:vrstica` + in druge wiki strani z relativnimi povezavami (`[oznaka](./stran.md)`) — + klikljivo v Forgeju, ustreznik Obsidianovih `[[wikipovezav]]`, prilagojen + repozitoriju. +3. **Ena odločitev na stran**, kjer je to izvedljivo; obilno navzkrižno + povezuj. +4. **Označi, ne tiho prepiši.** Ko nova koda nasprotuje strani, zabeleži + nasprotje (in ga razreši), namesto da bi tiho urejal zgodovino. +5. **Lintaj, ne zaupaj.** Stran je trditev, ki jo je treba preveriti proti + kodi, ne jamstvo. + +## Potek dela za lint + +Skripta [`wiki-lint`](../../scripts/wiki-lint) preveri vsako stran proti +trenutni kodi: viseče reference, obujena stara imena (iz imenika poimenovanj) +in osirotele strani. Teče kot del `ci-checks.sh --strict` in je zapahnjena s +kljuko pred potiskom — napaka odmika blokira potisk, enako kot opozorilo +clippy. + +## Strani + +| Stran | Kaj pokriva | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| [agent-harness](./agent-harness.md) | Razcep zot (agent) + Colibri (krmilna ravnina); samodejni zagon + gonilnik RPC | +| [agent-events-reference](./agent-events-reference.md) | Referenca dogodkov zot po opremi, preslikave Glasspane in preverjena polja prepisa | +| [cost-model](./cost-model.md) | Bajtno stabilne predpone, merjenje zadetkov predpomnilnika, samodejno stopnjevanje, stiskanje T14 | +| [glasspane](./glasspane.md) | Avtomat stanj agenta, pretakanje JSONL, taksonomija AgentRuntime, API posnetkov | +| [operator-attention](./operator-attention.md) | Izpeljan pogled "potrebuje operaterja": predikat pozornosti, vrstica/skok/filter TUI, robno sprožena terminalska opozorila | +| [headroom-sidecar](./headroom-sidecar.md) | Neobvezni stranski vagon za stiskanje rezultatov orodij in njegov protokol Unix vtičnice | +| [jail-confinement](./jail-confinement.md) | Trajne proti prehodnim ječam, pravilnik načina priv, ponovna uporaba omejitve zaganjalnika za strežnike MCP | +| [mother-hive](./mother-hive.md) | Arhitektura matičnega MCP — SSH s prisiljenim ukazom, enojni-dom-v-colibri, peer avtentikacija, ključ-na-semenu | +| [naming-decisions](./naming-decisions.md) | Imenik preimenovanj, nevtralnih glede na opremo / arhitekturnih — dostavljenih in v teku | +| [layered-soul](./layered-soul.md) | Kako Colibri danes uporablja repozitorij pregledanega konteksta layered-soul proti načrtovanemu | +| [task-board](./task-board.md) | Točkovanje po zmožnostih, cron razporejanje, praznjenje vnosne vrste, podlaga SQLite | +| [quality-gates](./quality-gates.md) | `ci-checks.sh` kot vrata pred združitvijo; zakaj je odmik prej dosegel `main` | +| [contracts](./contracts.md) | Stabilne JSON sheme (run-manifest, runtime-inventory, provider-smoke), zlati testi | +| [store-schema](./store-schema.md) | Usklajevalna shema SQLite in disciplina migracij | +| [external-mcp](./external-mcp.md) | Most MCP za urejevalnike + zunanji gostitelj stdio MCP; vrata za branje/pisanje/zunanji-klic | +| [operator-cli](./operator-cli.md) | CLI `colibri` kot tanek tipiziran odjemalec Unix vtičnice prek API demona | +| [tui](./tui.md) | Odjemalec terminalske nadzorne plošče (colibri-tui) proti avtomatu stanj colibri-glasspane | +| [terminal](./terminal.md) | Odločitev o terminalski zmožnosti (Kitty, razširjeno poročanje tipk, prehod tmux, SSH terminfo) | +| [runtime-inventory](./runtime-inventory.md) | Popis izvajalnega okolja gostitelja + bralnik statusa čuvaja; aditivne, bralne integracije | +| [skills-catalog](./skills-catalog.md) | Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI | +| [vault-provision](./vault-provision.md) | Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta | +| [deployment](./deployment.md) | Nameščevalnik gostitelja (clawdie): postavitev ZFS, storitev rc.d/systemd, varnost suhega teka | diff --git a/docs/wiki/sl/layered-soul.md b/docs/wiki/sl/layered-soul.md new file mode 100644 index 0000000..4440653 --- /dev/null +++ b/docs/wiki/sl/layered-soul.md @@ -0,0 +1,55 @@ +--- +title: Integracija plastovite duše +description: Kako Colibri danes uporablja repozitorij layered-soul in kaj je še načrtovano. +--- + +← [kazalo](./index.md) + +[clawdie/layered-soul](https://code.smilepowered.org/clawdie/layered-soul) je +prenosljiv, od opreme neodvisen vir trajne identitete in pregledanega +konteksta. Ta dokument beleži, kako ga Colibri uporablja **danes** in kaj je +še **načrtovano** — da pogodbe ne zamenjamo za v celoti zgrajeno. + +## Kar je povezano (deluje zdaj) + +Uvoz pregledanih **veščin** v Colibrijev obstoječi katalog `skills`: + + scripts/import-layered-soul.sh + +Prebere vsako datoteko SKILL.md veščine (frontmatter `name` / `description`; +kategorija `soul`) in `INSERT OR IGNORE` vrstico v tabelo `skills`. +`references/` in `templates/` znotraj veščine sta podporno gradivo, ne ločeni +veščini. Ista tabela kot `clawdie-iso/scripts/import-clawdie-skills.sh`; +idempotentno, varno za ponovni zagon. + +## Kar je odloženo (načrtovano, ne zgrajeno) + +Prilagoditveni vmesnik Colibri v layered-soul poimenuje "Plastovito +pomnilniško tkanino" s tremi shrambami — `system_skills`, `system_brain`, +`system_ops`. Na dan 2026-06-13 obstaja samo ena ploščata tabela `skills`; +ostalo je **samo načrt** (`docs/COLIBRI-SKILLS-PLAN.md`), zato uvoznik +namenoma ne cilja nanje. + +| Vir v layered-soul | Cilj (načrtovan) | Stanje | +| ---------------------------------- | ---------------- | ----------------------------------------------------------- | +| datoteke SKILL.md veščin | `system_skills` | uvoženo v ploščato tabelo `skills` danes | +| memories/urejene markdown datoteke | `system_brain` | NI uvoženo — shramba še ne obstaja (uvoznik poroča število) | +| pretvorjeni manifesti opravil | `system_ops` | NI implementirano | + +## Smer (enosmerno) + +`layered-soul` (git) je **vir resnice**; Colibri je **porabnik**. Uvoz teče +enosmerno (repo → Colibri). Veščine vedno uredite v izvornem repozitoriju, +nato ponovno uvozite — izvajalne kopije so prehodni porabniki. + +## Zapiranje vrzeli (prihodnje delo) + +1. Implementiraj `system_brain` po `COLIBRI-SKILLS-PLAN.md`, nato razširi + uvoznika, da naloži urejene spomine. +2. Preseli ploščato tabelo `skills` v načrtovano shemo `system_skills`. +3. Definiraj in uvozi manifeste opravil `system_ops`. + +## Glej tudi + +- [skills-catalog](./skills-catalog.md) — Colibrijev bralni izvajalni porabnik veščin +- [store-schema](./store-schema.md) — načrtovane tabele `system_skills` / `system_brain` diff --git a/docs/wiki/sl/mother-hive.md b/docs/wiki/sl/mother-hive.md new file mode 100644 index 0000000..d3cd291 --- /dev/null +++ b/docs/wiki/sl/mother-hive.md @@ -0,0 +1,119 @@ +--- +title: Matični hive +description: Kako matično vozlišče (OSA) usklajuje USB-operaterska vozlišča prek MCP prek SSH → PostgreSQL. +--- + +← [kazalo](./index.md) + +## Kaj je to + +Matično vozlišče (OSA) usklajuje USB-operaterska vozlišča prek MCP prek SSH → +PostgreSQL. USB-vozlišča pošiljajo profile strojne opreme; mati izpelje +zmožnosti in vzdržuje hive register. Ta stran beleži **odločitve**, ki stojijo +za izvedbo — utemeljitve, ki jih koda ne more izraziti. Za navodila za +namestitev, arhitekturne diagrame in kontrolni seznam prvega zagona glejte +[`packaging/mother/MOTHER-SETUP.md`](../packaging/mother/MOTHER-SETUP.md). + +## Odločitve + +### Meja SSH s prisiljenim ukazom (ne poslušajoči demon) + +USB-vozlišča dosežejo mater tako, da zaženejo `ssh colibri@mother` (brez +oddaljenega ukaza). Na materini strani `authorized_keys` vsili +`command="/usr/local/bin/colibri-mcp-ssh",restrict,...` — povezava **ne more** +zagnati interaktivne lupine ali kateregakoli ukaza razen ovoja. + +Ovoj (`colibri-mcp-ssh`) dodatno dovoli `SSH_ORIGINAL_COMMAND` samo kot `""` +(stdio MCP način) ali `"tools"` (enkratno odkritje). Vsaka druga vrednost je +zavrnjena. + +**Zakaj ne poslušajoči demon** (HTTP, gRPC, surovi TCP): Tailscale šifrira +prenos, zato plast SSH doda avtentikacijo in omejitev brez dodatne +infrastrukture (brez TLS certifikatov, brez avtentikacijskih žetonov, brez +odprtih vrat). Meja s prisiljenim ukazom je druga ključavnica poleg SSH +ključa — tudi ogroženi USB, ki drži ključ, lahko samo pokliče ovoj, ovoj pa +samo delegira colibri-mcp. Obramba v globino, nameščena kot ena funkcija +OpenSSH. + +→ [`colibri-mcp-ssh`](../packaging/mother/colibri-mcp-ssh), +[`MOTHER-SETUP.md` §Varnost](../packaging/mother/MOTHER-SETUP.md#varnostne-lastnosti) + +### En sam dom za matično infrastrukturo (colibri, ne clawdie-iso) + +Matični MCP skripti (`node-register-mcp`, `geodesic-dome-mcp` itd.) so bili +prvotno kopirani v oba repozitorija. Kopija v clawdie-iso je odnesla — njen +`node-register-mcp` je uporabljal interpolacijo nizov `E'${...}'` (dovzetno +za SQL-injekcijo), medtem ko je kopija v colibri uporabljala parametrizirani +`psql -v :'variable'`. Kopija v iso je bila odstranjena v clawdie-iso PR #129. + +**Nauk**: skripta v dveh repozitorijih **bo** odnesla. Wiki lint je +enorepozitorijski in ne vidi podvojenih skript med repozitoriji. Zmanjšanje +tveganja je disciplina: matična infrastruktura živi na enem mestu. + +→ [naming-decisions §Strukturne](./naming-decisions.md#strukturne-odločitve) +(vrstica "En sam dom") + +### `hive_nodes` — ne `usb_nodes` + +Prvotno ime tabele je predpostavljalo, da se bodo registrirala samo +USB-zagnana vozlišča. Toda vozlišče je vsak gostitelj, ki se pridruži hive — +USB, NVMe, ječa. Preimenovano v `hive_nodes` s stolpcem `node_type` (colibri +#161). Sprožilec `derive_capabilities()` je agnostičen glede tabele in ob +INSERT samodejno izračuna `has_gpu`, `gpu_vendor`, `can_run_local_llm`, +`has_wifi`, `max_model`. + +→ [`mother_schema.sql`](../packaging/mother/mother_schema.sql), +[naming-decisions](./naming-decisions.md) (vrstica `usb_nodes → hive_nodes`) + +### PostgreSQL peer avtentikacija (brez gesel) + +Uporabnik OS `colibri` se poveže na `mother_hive` prek peer avtentikacije — +jedro potrdi Unix uporabnika, geslo ni potrebno. `node-register-mcp` teče kot +ta uporabnik in podeduje zaupanje. Brez datotek pgpass, brez spremenljivk +okolja, brez vrtenja poverilnic. En gibljivi del: pravilo `peer` v +`pg_hba.conf` mora biti pred morebitno vrstico `local all all` (prvo +ujemanje). + +**Zakaj ne geslo ali certifikat**: gesla se vrtijo in uhajajo; certifikati +potrebujejo CA. Peer avtentikacija je vgrajena v PostgreSQL na vsakem Unixu +in deluje za povezavo localhost z nič konfiguracije razen ene vrstice v +`pg_hba.conf`. + +→ [`MOTHER-SETUP.md` §Namestitev, 6. korak](../packaging/mother/MOTHER-SETUP.md#enkratna-namestitev) + +### Ključ na semenski particiji, ne v sliki + +Zasebni ključ `mother-mcp` je nameščen na particijo CLAWDIESEED, ne zapečen v +ISO. Gradbeni skript ima varovalko za izdajo, ki **zavrne** vgradnjo ključa v +sliko za izdajo. Uvoznik semena (`clawdie-live-seed`) ga namesti ob zagonu. + +**Zakaj**: ISO za izdajo je prenosljiv artefakt. Vgradnja zasebnega ključa +vanj bi vsakemu prenašalcu dala dostop do materinega MCP. Semenska particija +je ločen fizični medij, ki ga nadzoruje operater. Tudi brez semena se ISO +zažene in deluje — zunanja MCP povezava demona do matere odpove elegantno +(SSH: "config file not found"), vozlišče pa deluje samostojno. + +→ [naming-decisions](./naming-decisions.md) ("Znani ostanek"), clawdie-iso #133 + +### Demonov uporabnik, ne operater + +Colibri demon teče kot uporabnik `colibri` (`/var/db/colibri`), ne kot +operater (`clawdie`, `/home/clawdie`). Zunanjo MCP SSH povezavo do matere +zažene demon — zato morajo biti SSH ključ, konfiguracija in known_hosts v +demonovem domu. Uvoznik semena namesti SSH gradivo v **oba** domova (operater + +- demon). + +**Zakaj ne preprosto v clawdiejev dom in `sudo`**: demon ni operater. Tek kot +ločen uporabnik pomeni, da je domet ogroženega demona omejen na tisto, kar +uporabnik `colibri` lahko počne — MCP klici do matere, ne operaterske +datoteke ali `sudo`. + +→ [`clawdie-live-seed` (clawdie-iso)](https://code.smilepowered.org/clawdie/clawdie-iso/src/branch/main/live/operator-session/clawdie-live-seed), +[`MOTHER-SETUP.md` §Upravljanje ključev](../packaging/mother/MOTHER-SETUP.md#upravljanje-ključev) + +## Glej tudi + +- [agent-harness](./agent-harness.md) — razcep zot/Colibri; samodejni zagon +- [naming-decisions](./naming-decisions.md) — `usb_nodes → hive_nodes`, preimenovanje zastavice autospawn +- [quality-gates](./quality-gates.md) — vrata, ki bi morala ujeti odmik ob času PR diff --git a/docs/wiki/sl/operator-attention.md b/docs/wiki/sl/operator-attention.md new file mode 100644 index 0000000..c1523f9 --- /dev/null +++ b/docs/wiki/sl/operator-attention.md @@ -0,0 +1,146 @@ +--- +title: Operaterska pozornost — "ali ta agent potrebuje mene zdaj?" +description: Kako Glasspane presoja, kateri agent potrebuje operaterski poseg, in to prikaže v TUI. +--- + +← [kazalo](./index.md) + +## Kaj je to + +Nadzorna hrbtenica Glasspana odgovarja na vprašanje _"v kakšnem stanju je ta +agent?"_. Pozornost je plast nad njo, ki odgovarja na vprašanje, ki si ga +operater dejansko zastavi najprej: _"ali katerikoli agent potrebuje mene +**zdaj**?"_ Je **izpeljan pogled** nad avtomatom stanj in terminalom, +prikazan v TUI in podprt z robno sproženimi opozorili — ne šesto stanje, ne +nov podsistem. + +## Odločitve + +### Pozornost je pogled, ne stanje + +`AgentState` ostaja majhen (`Idle`, `Working`, `Blocked`, `Done`, `Error`). +"Potrebuje operaterja" je prost predikat nad njim, ne dodatna različica: + +```rust +fn needs_attention(pane: &Pane) -> bool { + pane.state == AgentState::Error + || pane.state == AgentState::Blocked + || pane.stalled +} +``` + +`Blocked` je vključen, ker dokumentacijski komentar avtomata stanj pravi, da +pomeni "čaka na usmerjanje / odobritev / vnos" — tj. agent je parkiran na +operaterju. En predikat, ki ga uporabljajo pozornostna vrstica, filter in +tipke za skok, zato se definicija spremeni na enem mestu. + +`stalled` je tudi sam izpeljan — podokno je stalled, ko v +`DEFAULT_STALL_AFTER` (4 ure) ni prispel noben dogodek. Namenoma je redek: +pozornost so večinoma podokna v stanju Error in Blocked; Stalled je stopnjevanje +"nekaj je globoko narobe", ne pogost pojav. + +→ [`crates/colibri-glasspane/src/lib.rs`](../../crates/colibri-glasspane/src/lib.rs) +(`AgentState`, `SupervisedPane::is_stalled_at`, `DEFAULT_STALL_AFTER`) + +### TUI naredi pozornost nemogoče spregledati + +Ko katerokoli podokno v **trenutnem pogledu** potrebuje pozornost, se običajna +glava zamenja z rdeče obrobljeno pozornostno vrstico, ki navaja zadevna +podokna. Vrstice, ki potrebujejo pozornost, dobijo obrnjeno ozadje; kazalka se +obrne znova, da operater še vedno vidi, katera je izbrana. Dve tipki za skok +(`n` / `N`) krožita naprej/nazaj skozi pozornostna podokna z ovijanjem, `a` +pa preklaplja filter samo za pozornost. Vsi trije delujejo nad že filtriranim +naborom podoken. + +**Sestavljanje filtrov je IN.** Pozornostni filter se sestavlja s filtrom +seje, zato vrstica odraža samo tisto, kar operater gleda. Junija 2026 je bil +dostavljen hrošč, kjer je bil `has_attention` izračunan iz _nefiltriranega_ +posnetka: napaka v seji `s2` je prižgala vrstico med gledanjem seje `s1`, +lastni `filtered_panes()` vrstice pa je nato zgodaj vrnil prazen izris — +operater je tako izgubil glavo zaradi praznega rdečega okvirja. Popravljeno z +izračunom pozornosti iz `filtered_panes()`; pokrito s preskusom upodabljanja +med sejami. + +**Past `NO_COLOR`.** Seje Hermesa puščajo `NO_COLOR=1` v okolja podprocesov +in crossterm to konvencijo upošteva. Brez `force_color_output(true)` ob zagonu +se `colibri-tui`, zagnan iz seje Hermesa, upodablja brez barv — rdeča +pozornostna vrstica postane nevidna. Funkcija `main()` vsili barve ne glede na +starševsko okolje; to je nadzorna plošča TUI, barve so nosilne. + +Prihodnja izboljšava: prikaz pozornostne vrstice **in** glave hkrati (dvojni +pogled) namesto zamenjave ene z drugo, da operater na en pogled vidi število +podoken in pozornostna podokna, brez preklapljanja. + +→ [`crates/colibri-glasspane-tui/src/main.rs`](../../crates/colibri-glasspane-tui/src/main.rs) +(`needs_attention`, `render_attention_bar`, `attention_indices`) + +### Zajem terminala je dopolnilni signal + +Avtomat stanj je _"kar agent pove"_ (strukturirani dogodki JSONL). Zajem +terminala je _"kar prikazuje zaslon"_ — dejansko besedilo podokna, razvrščeno +po znanih okvarjenih vzorcih. Podokno je lahko `Working`, medtem ko njegov +zaslon kaže `Active: failed (Result: exit-code)`. Pozornost je pogled nad +**obema**. + +`TerminalRecorder` hrani omejeno zgodovino okvirjev (`DEFAULT_HISTORY_CAPACITY` += 256 okvirjev). Identiteta okvirja je **SHA-256 očiščenega besedila**, zato +se poizvedovanje skoraj statičnega podokna vsako sekundo strne v zgoščen +dnevnik dejanskih prehodov stanja namesto tisočev podvojenih okvirjev. +`capture_tmux_pane` za zajem pokliče `tmux`, toda `observe()` sprejme surovo +besedilo neposredno — logika razpoznavanja in triaže je v celoti preizkusljiva +brez priključenega terminala. + +→ [`crates/colibri-glasspane/src/terminal.rs`](../../crates/colibri-glasspane/src/terminal.rs) +(`TerminalRecorder`, `Observation`, `capture_tmux_pane`) + +### Triaža prepoznav, podatkovno gnana po OS + +`SignatureSet` pregleda očiščeno besedilo terminala in razvrsti zaslon v +`failures` / `warnings` / `info` / `healthy` (`Severity::{Error, Warn, Info, Ok}`). +Vzorci se ujemajo kot podnizi brez razlikovanja velikosti črk; prvi zadetek +zabeleži prepoznavo in ni poročan dvakrat. Vsak zadetek nosi človeški +`next_action` in neobvezni `invoke` (veščino, ki jo agent lahko zažene za +odpravo) — zadetek ni "nekaj se je zgodilo", ampak "tukaj je, kaj to pomeni +in kaj storiti". + +Mehanizem zaznavanja je **podatkovno gnan**: gostitelj FreeBSD in gostitelj +Linux naložita različne nabore `Signature`, a si delita isti ujemalnik. +`SignatureSet::linux_default` prinaša majhen začetni nabor; klicatelji +zgradijo svojega z `SignatureSet::new`. To je gumb na OS, na katerega se +opira Colibrjevo usmerjanje po zmožnostih. + +→ [`crates/colibri-glasspane/src/signatures.rs`](../../crates/colibri-glasspane/src/signatures.rs) +(`SignatureSet`, `Severity`, `Signature`, `Detection::alertable`) + +### Opozorila so robno sprožena, ne nivojsko + +Prepoznava napake/opozorila se sporoči **samo ob okvirju, kjer se prvič +pojavi**, ne ob vsakem naslednjem okvirju, ki jo še prikazuje — vrnjeno kot +`Observation::Recorded { uuid, new_alerts }` samo z novimi sproženimi +zadetki. Ko se stanje počisti in pozneje ponovi, se sproži znova. Nivojsko +sprožena opozorila ob 1s poizvedovanju bi ponovno obveščala vsako sekundo za +čas trajanja zataknjenega podokna; robno sproženje pomeni, da vsako opozorilo +pomeni "to se je pravkar začelo". + +→ [`crates/colibri-glasspane/src/terminal.rs`](../../crates/colibri-glasspane/src/terminal.rs) +(`TerminalRecorder::observe`, `Observation::new_alerts`) + +## Kaj je še odprto + +- **Izhodno potiskanje.** Pozornost je prikazana na zaslonu (vrstica, + poudarjanje). Operater nadzoruje brezglave gostitelje prek Tailscale, ne z + gledanjem TUI. Potiskanje pozornosti **navzven** — namizno obvestilo na živi + sliki in sporočilo Telegram — je najpomembnejši nedokončan kos. Žeton je že + pripravljen; prenos (`colibri notify` proti dogodku glasspane, ki ga sproži + kljuka harnessa) je neodločen. +- **Odgovarjanje blokiranemu agentu z nadzorne plošče.** API posnetkov je + namenoma bralno usmerjen. Pisalna pot ("pošlji vnos v podokno N" prek + vtičnice demona) bi operaterju omogočila, da se odzove na `Blocked` podokno + iz TUI. Spremeni vtičnico iz nadzora v interaktivno upravljanje — lasten + načrtovalski prehod. + +## Glej tudi + +- [glasspane](./glasspane.md) — avtomat stanj, nad katerim je pozornost pogled +- [tui](./tui.md) — nadzorna plošča, ki prikazuje pozornost +- [terminal](./terminal.md) — terminalska zmožnost, na katero se opirajo bližnjice pozornosti diff --git a/docs/wiki/sl/task-board.md b/docs/wiki/sl/task-board.md new file mode 100644 index 0000000..0d6d317 --- /dev/null +++ b/docs/wiki/sl/task-board.md @@ -0,0 +1,101 @@ +--- +title: Tabla opravil + razporejevalnik +description: Kako Colibri hrani operaterska opravila in jih razporeja med agente glede na zmožnosti. +--- + +← [kazalo](./index.md) + +## Kaj je to + +Colibrjeva tabla opravil hrani delovne naloge, ki jih odda operater, razporejevalnik +pa jih ob vsakem taktu dodeli najprimernejšemu agentu. Opravila pritekajo prek +Unix vtičnice demona (`create-task`, `intake-task`), prazni pa jih zanka +razporejevalnika, ki teče znotraj demona vsakih ~30 sekund. + +## Odločitve + +### Točkovanje po zmožnostih (najboljše ujemanje, ne prvo) + +Ko razporejevalnik izbira agenta za opravilo, točkuje vsakega razpoložljivega +agenta glede na **zahtevane zmožnosti** opravila s preprostim štetjem preseka: +`|zahtevane ∩ agentove_zmožnosti| / |zahtevane|`. Agent z najvišjim številom +točk zmaga; izenačenja razreši ime agenta (deterministično, da ponovni teki ne +premetavajo). + +Opravilo z `["freebsd", "zfs"]` se bo ujemalo z agentom, ki ima obe zmožnosti, +pred tistim, ki ima samo `freebsd`. Opravilo brez zahtevanih zmožnosti ustreza +vsakemu agentu. Agenti brez povezave in agenti, katerih zmožnosti se sploh ne +sekajo, so preskočeni. + +**Zakaj ne krožno ali FIFO**: ujemanje po zmožnostih pomeni, da pravi agent +dobi pravo delo brez operaterskega ročnega dodeljevanja. Točkovanje je +preprosto (presek množic) in pregledno — brez strojnega učenja, brez uteži za +uglaševanje. + +→ [`crates/colibri-daemon/src/scheduler.rs`](../../crates/colibri-daemon/src/scheduler.rs) +(`capability_match_score`, `pick_agent`) + +### Tri vrste urnikov (cron, interval, enkrat) + +| Vrsta | Obnašanje | +| -------- | -------------------------------------------------------------- | +| Cron | Sproži ob določenem stenskem času (npr. `0 0 * * *` = polnoč). | +| Interval | Sproži po določenem trajanju od zadnjega teka (npr. 3600s). | +| Enkrat | Sproži natanko enkrat, ob določenem prihodnjem času. | + +Cron vzorci so preprosti 5-poljski izrazi (minuta, ura, dan, mesec, dan v +tednu) z nadomestnimi znaki — brez sekundne natančnosti, brez sintakse +`/step`. Ujemanje uporablja primerjavo predpone: cron vzorec se ujema, če se +vsako polje trenutnega časa začne z nizom vzorca, torej `0` ustreza `00`, `1` +ustreza `10-19` itd. To je namenoma preprosto — cron je pripomoček za +periodično hišno opravilo, ne splošni opravilni pogon. + +**Zakaj ne prava cron knjižnica**: naloga razporejevalnika je razpošiljanje +opravil agentom, ne upravljanje koledarja. Preprosti predponski cron pokrije +90 % primerov uporabe (dnevne gradnje, urna poročila) brez dodatne odvisnosti +za razčlenjevanje. + +→ [`crates/colibri-daemon/src/scheduler.rs`](../../crates/colibri-daemon/src/scheduler.rs) +(`should_fire`) + +### Praznjenje vnosne vrste (vrsta → tabla opravil → agent) + +Ukaz `intake-task` prek vtičnice potisne opravilo v vnosno vrsto. Ob vsakem +taktu razporejevalnika (~30s) zanka izprazni vnosno vrsto v shrambo SQLite na +tabli opravil, nato preveri zapadla načrtovana opravila. To dvofazno +praznjenje loči oddajo od izvajanja: operater odds kadar koli, razporejevalnik +obdeluje v paketih. + +Opravila v vnosni vrsti nosijo **niz zmožnosti** (ne ID agenta). +Razporejevalnik izbere najboljšega agenta ob času izvajanja, zato bo opravilo, +oddano ko noben ujemajoči agent ni na voljo, prevzeto, ko se eden poveže. + +**Zakaj vnosna vrsta in ne neposredna dodelitev**: agenti prihajajo in +odhajajo. Če bi oddaja zahtevala izbiro agenta, bi operater moral vedeti, +kateri agenti so na voljo — sklopitev, ki se ji tabla opravil namenoma izogne. + +→ [`crates/colibri-daemon/src/scheduler.rs`](../../crates/colibri-daemon/src/scheduler.rs) +(`Scheduler`, `add_job`, `submit`), +[`crates/colibri-daemon/tests/intake_scheduler_loop.rs`](../../crates/colibri-daemon/tests/intake_scheduler_loop.rs) + +### Podlaga SQLite (vgrajeno, ne storitev) + +Tabla opravil hrani opravila, registracije agentov, podatke o najemnikih in +katalog veščin v vgrajeni podatkovni zbirki SQLite na +`/var/db/colibri/colibri.sqlite`. Brez ločenega podatkovnega procesa — demon +odpre datoteko neposredno. + +**Zakaj SQLite, ne PostgreSQL**: demon teče na operaterskem USB-ju in na +nameščenih gostiteljih. Polna storitev PostgreSQL je pretežka za +koordinacijsko stanje enega samega demona. SQLite je brez konfiguracije, brez +administracije in preživi ponovne zagone demona brez ločenega življenjskega +cikla. Matično vozlišče uporablja PostgreSQL za hive register, ker je +večnajemniško; krajevni demon je enonajemniški. + +→ [`crates/colibri-store/src/lib.rs`](../../crates/colibri-store/src/lib.rs) + +## Glej tudi + +- [mother-hive](./mother-hive.md) — matični hive register, osnovan na PostgreSQL +- [cost-model](./cost-model.md) — sledenje stroškov po seji +- [agent-harness](./agent-harness.md) — samodejni zagon -- 2.45.3 From d9ef0a94e259021b90744cdb47c48e724cb0ed29 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:05:30 +0200 Subject: [PATCH 02/19] docs(sl): install pages use clawdie flow (drop just install) Co-Authored-By: Claude Opus 4.8 --- docs/guide/sl/install/controlplane-install.md | 24 ++---- docs/guide/sl/install/index.md | 2 +- docs/guide/sl/install/install.md | 73 +++++++++++++++++++ docs/guide/sl/install/requirements.md | 8 +- 4 files changed, 84 insertions(+), 23 deletions(-) create mode 100644 docs/guide/sl/install/install.md diff --git a/docs/guide/sl/install/controlplane-install.md b/docs/guide/sl/install/controlplane-install.md index 97ca5af..e9231ed 100644 --- a/docs/guide/sl/install/controlplane-install.md +++ b/docs/guide/sl/install/controlplane-install.md @@ -1,24 +1,16 @@ --- title: 'Namestitev krmilne ravnine' -description: Namestite krmilno ravnino Clawdie s standardnim orkestratorjem. +description: Namestite gostiteljsko storitev krmilne ravnine Clawdie z binarno datoteko clawdie. --- -Krmilno ravnino namesti standardni orkestrator: +Krmilna ravnina teče kot storitev `clawdie` (`colibri-daemon`), ki jo pripravi +binarna datoteka `clawdie`: ```bash -just install +cargo build -p clawdie --release +clawdie apply --yes ``` -Root namestitev poganja krmilno ravnino kot storitev Clawdie, ki jo upravlja -gostitelj. Orkestrator skupaj nastavi PF, delovne ječe, PostgreSQL, hostd, -namestitev storitve, kontrolne točke in stanje za nadaljevanje. - -Če namestitev ne uspe, nadaljujte od neuspelega koraka: - -```bash -just install-from-db -just install-from hosts -just install -- --dry-run -``` - -Kanonično ime mostu Bastille/Warden je `warden0`. +Najprej si oglejte načrt z `clawdie plan` (`apply` je suhi tek, dokler ne dodate +`--yes`). Za celoten nabor ukazov in strategijo shrambe glejte +[Namestitev](./install/). Kanonično ime mostu Bastille/Warden je `warden0`. diff --git a/docs/guide/sl/install/index.md b/docs/guide/sl/install/index.md index 055c0c3..3360809 100644 --- a/docs/guide/sl/install/index.md +++ b/docs/guide/sl/install/index.md @@ -21,5 +21,5 @@ To pot uporabite za nov stroj ali ponovno namestitev z zagonskega medija. To pot uporabite, kadar je FreeBSD 15.x že nameščen in gostitelja upravljate sami. - [Zahteve](./requirements/) — zahteve glede gostitelja, izvajalnega okolja in orodjarne. -- [Namestitveni orkestrator](./install/) — zaženite `just install` in nadaljujte neuspele korake. +- [Namestitev](./install/) — pripravite gostiteljsko storitev z binarno datoteko `clawdie` (`clawdie discover` / `plan` / `apply --yes`). - [Kontrolni seznam za svežo namestitev](./fresh-install-checklist/) — preverite dokončano namestitev. diff --git a/docs/guide/sl/install/install.md b/docs/guide/sl/install/install.md new file mode 100644 index 0000000..f9b7393 --- /dev/null +++ b/docs/guide/sl/install/install.md @@ -0,0 +1,73 @@ +--- +title: Namestitev +description: Pripravite gostiteljsko storitev Clawdie z binarno datoteko clawdie. +--- + +**Ukaz:** `clawdie apply --yes` + +Clawdie namesti binarna datoteka `clawdie` (`crates/clawdie`). Zazna postavitev +ZFS na gostitelju in pripravi storitev `clawdie`: nabore podatkov za shrambo, +storitveni račun ter enoto rc.d (FreeBSD) / systemd (Linux), ki poganja +`colibri-daemon`. Izgradite jo iz delovnega prostora Cargo: + +```bash +cargo build -p clawdie --release +``` + +## Ukazi + +```bash +clawdie discover # samo branje: OS, bazeni ZFS, nabori podatkov, proste plošče +clawdie plan [--pool IME] # prikaže načrt namestitve (suhi tek, brez pisanja) +clawdie apply [--pool IME] # suhi tek, razen če dodate --yes +clawdie apply --yes # pripravi: postavitev shrambe + namesti storitev +``` + +`apply` je **privzeto suhi tek** in izpiše celoten načrt korakov; na disk piše le +z `--yes`. Z enim bazenom ZFS se ta izbere samodejno; z več jih navedite z +`--pool IME`. + +## Strategija shrambe + +| Gostitelj | Vedenje | +| ---------------------- | --------------------------------------------------------------------------- | +| FreeBSD | ZFS je **zahtevan**; nabori podatkov nastanejo pod izbranim bazenom. | +| Linux + ZFS + bazen | Enako — nabori podatkov pod bazenom. | +| Linux, brez ZFS/bazena | Preklopi na navadne imenike in poroča o prednostih ZFS ter prostih ploščah. | + +Postavitev ZFS pod bazenom: + +```text +/clawdie (vsebnik, canmount=off) +/clawdie/db -> /var/db/clawdie +/clawdie/log -> /var/log/clawdie +``` + +## Kaj pripravi `apply --yes` + +1. **Shramba** — zgornji nabori podatkov (ali navadna `/var/db/clawdie` + + `/var/log/clawdie` pri preklopu na navadne imenike). +2. **Storitveni račun** — `clawdie` (nologin), lastnik stanja + (`clawdie:clawdie`). +3. **Storitev** — enota rc.d (FreeBSD) / systemd (Linux), nameščena in omogočena + za poganjanje `/usr/local/bin/colibri-daemon`. + +## Ustvarjanje bazena (uničujoče) + +Na gostitelju s prosto ploščo in brez uporabnega bazena: + +```bash +clawdie apply --pool IME --create-pool /dev/PLOSCA --yes +``` + +`--create-pool` požene `zpool create` na `PLOSCA` in **uniči vse podatke na +njej**, zato je zavrnjeno, razen če je plošča zaznana kot prazna. Stražo preglasi +`--force`, le če ste prepričani. + +## Varnost + +Koraki, ki se dotikajo diska, tečejo kot root na ciljnem gostitelju. `discover`, +`plan` in goli `apply` nikoli ne pišejo — najprej preglejte z `plan`. + +Priprava ječ, baze in spletne storitve (CMS) še ni del namestitvenega programa +colibri. diff --git a/docs/guide/sl/install/requirements.md b/docs/guide/sl/install/requirements.md index c912f64..86be56a 100644 --- a/docs/guide/sl/install/requirements.md +++ b/docs/guide/sl/install/requirements.md @@ -5,7 +5,7 @@ description: Zahteve glede gostitelja, izvajalnega okolja in orodjarne za Clawdi Kaj potrebujete na gostitelju pred namestitvijo Clawdie. Namestitveni program z ISO večino tega samodejno pripravi; namestitve na obstoječem gostitelju naj te -zahteve preverijo pred zagonom `just install`. +zahteve preverijo pred zagonom `clawdie apply`. ## Gostitelj @@ -18,11 +18,7 @@ zahteve preverijo pred zagonom `just install`. ## Orodjarna -- **Rust** prek rustup, nameščen pod `/opt/clawdie/rustup`. Potreben za domorodne - odvisnosti (SWC, tree-sitter). ISO ga namesti; namestitve na obstoječem - gostitelju ga zaženejo iz - [`Namestitvenega orkestratorja`](./install). -- **Node.js + tsx** za namestitvene skripte in izvajalno okolje. +- **Rust** (Cargo) — izgradite z `cargo build -p clawdie --release`. Glejte [Namestitev](./install/). - **Bastille** za upravljanje ječ. ## Filozofija izvajalnega okolja -- 2.45.3 From 3ec68ff860800a70cf22ed186facc0f6eda307c0 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:01:57 +0200 Subject: [PATCH 03/19] =?UTF-8?q?docs(sl):=20translate=20wiki=20group=201?= =?UTF-8?q?=20=E2=80=94=20glasspane,=20agent-harness,=20naming,=20quality-?= =?UTF-8?q?gates,=20store-schema?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/wiki/sl/agent-harness.md | 60 +++++++++++++ docs/wiki/sl/glasspane.md | 150 +++++++++++++++++++++++++++++++ docs/wiki/sl/naming-decisions.md | 63 +++++++++++++ docs/wiki/sl/quality-gates.md | 53 +++++++++++ docs/wiki/sl/store-schema.md | 145 ++++++++++++++++++++++++++++++ 5 files changed, 471 insertions(+) create mode 100644 docs/wiki/sl/agent-harness.md create mode 100644 docs/wiki/sl/glasspane.md create mode 100644 docs/wiki/sl/naming-decisions.md create mode 100644 docs/wiki/sl/quality-gates.md create mode 100644 docs/wiki/sl/store-schema.md diff --git a/docs/wiki/sl/agent-harness.md b/docs/wiki/sl/agent-harness.md new file mode 100644 index 0000000..b936de4 --- /dev/null +++ b/docs/wiki/sl/agent-harness.md @@ -0,0 +1,60 @@ +--- +title: Agentska oprema: zot + Colibri +description: Dve binarni datoteki, ne ena — zot (agent, Go) in Colibri (krmilna ravnina, Rust). +--- + +← [kazalo](./index.md) + +## Odločitev + +Dve binarni datoteki, ne ena (Sam je zavrnil združitev, 13. junij 2026): + +- **zot** — _agent_ (vhodna vrata do modela). Binarna datoteka Go; deluje. +- **Colibri** — _krmilna ravnina_ (nadzornik). Rust; opazuje agente prek + glasspane, poganja tablo opravil, upravlja stroške. **Opazuje** zot/pi; ne + vsebuje ju. + +Kanonična izjava: `AGENTS.md` (vrstice ~18–32). `clawdie-ai` (TS) se krči; +preživele funkcije se selijo v zot/Colibri. + +> **Ni** dokumenta `ADR-agent-harness-consolidation.md` (v preteklosti je bil +> omenjen; te reference so bile od takrat očiščene). Obravnavaj `AGENTS.md` +> kot ADR. + +## Izvajalna okolja + +Glasspane normalizira dogodke iz obeh oprem v eno taksonomijo prek +`AgentRuntime { Pi, Zot, Local }` — `crates/colibri-glasspane/src/lib.rs` +(`zot_event_type()` preslika zotove dogodke na imena v slogu pi). + +## Samodejni zagon + gonilnik RPC (colibri#143) + +Pogodba zaganjalnika: zaženi agenta, beri stdout JSONL. + +- **pi** se sam poganja (`pi --mode json`) s `stdin` null — ustreza + neposredno. +- Edini strukturirani trajni način **zot** je `zot rpc`, vrstnik + zahteva/odgovor, ki **bere stdin**. Zato zaganjalnik napelje stdin za RPC + agente in demon pošlje poziv prek `RpcSender`. + +Kje živi: + +- pogodba zaganjalnika + `rpc_stdin` + `RpcSender`: `crates/colibri-daemon/src/spawner.rs` +- argv samodejnega zagona, ki se zaveda binarne datoteke (`zot → rpc`, pi → `--mode json`): + `crates/colibri-daemon/src/socket.rs` (`default_agent_args`, `autospawn_agent_if_configured`) +- žični format (preverjen proti pravemu zot): [agent-events-reference](./agent-events-reference.md) +- dokaz od konca do konca, zot: `crates/colibri-daemon/tests/zot_rpc_smoke.rs` + (`#[ignore]`, `ZOT_BIN`-pogojen — potrebuje pravo binarno datoteko zot) +- dokaz od konca do konca, pi: `crates/colibri-daemon/tests/pi_spawn_live.rs` + (ne-ignoriran, teče v vsakem `cargo test` — uporablja `sample-pi-agent.py`, ki + oddaja taksonomijo colibri-pi-events, preverjeno proti pravemu pi) +- pogodba argv samodejnega zagona: `crates/colibri-daemon/src/socket.rs` + (testi enot `default_agent_args` — zot→rpc, pi→--mode json) + +Privzeta oprema OOTB je **zot**; pi ostaja podprta rezerva +(`COLIBRI_AUTOSPAWN_BINARY=pi`). + +## Glej tudi + +- [naming-decisions](./naming-decisions.md) — nevtralno poimenovanje `pi → zot` +- [quality-gates](./quality-gates.md) — kako je napol dokončano preimenovanje doseglo `main` diff --git a/docs/wiki/sl/glasspane.md b/docs/wiki/sl/glasspane.md new file mode 100644 index 0000000..ced9ac8 --- /dev/null +++ b/docs/wiki/sl/glasspane.md @@ -0,0 +1,150 @@ +--- +title: Glasspane — nadzor stanja agentov +description: Colibrijeva plast za opazovanje agentov. Gleda podprocese agentov prek JSONL, zlaga tok v semantični avtomat stanj in izpostavlja API posnetkov. +--- + +← [kazalo](./index.md) + +## Kaj je to + +Glasspane je Colibrijeva plast za opazovanje agentov. Opazuje podprocese +agentov prek njihovega stdout JSONL, zlaga tok v semantični avtomat stanj +(`Idle → Working → Done`) in izpostavlja API posnetkov za nadzorne plošče in +koordinacijo demona. Vsak zagnani agent — Pi, zot ali krajevni sample — se +pretaka skozi isti vnosnik in konča v isti taksonomiji. + +## Odločitve + +### Stanje agenta kot avtomat stanj, ne surovi dnevnik dogodkov + +Glasspane ne posreduje samo surovih agentskih dogodkov. Zaužije vrstice JSONL +in prehaja **poimenovano podokno** skozi končno množico stanj: + +``` +Idle → Working → Blocked → Done + ↳ Error +``` + +Enum `AgentState` (`Idle, Working, Blocked, Done, Error`) je namenoma majhen. +Zajame tisto, kar nadzornik potrebuje vedeti — "ali agent dela? je blokiran? +je končal?" — brez kodiranja agentsko-specifične semantike. Dogodki, ki ne +spremenijo stanja (npr. poročilo o uporabi iz zot), so zabeleženi v metapodatkih +podokna, vendar ne vplivajo na avtomat stanj. + +`Stalled` **ni** šesta različica — je izpeljana zastavica: podokno je stalled, +ko v `DEFAULT_STALL_AFTER` (4 ure) ni prispel noben dogodek. Izpeljano +pozornost (Error / Blocked / Stalled) pokriva +[operator-attention](./operator-attention.md). + +**Zakaj ne preprosto slediti dnevniku**: surovi dnevniki dogodkov so +agentsko-specifični in se sčasoma spreminjajo (zot dodaja nove vrste +dogodkov). Avtomat stanj je stabilna pogodba, na katero se lahko zanesejo +demon, TUI in odjemalski CLI. + +→ [`crates/colibri-glasspane/src/lib.rs`](../../crates/colibri-glasspane/src/lib.rs) + +### Pretakanje JSONL (ena vrstica = en dogodek) + +Agenti oddajajo strukturirane dogodke kot JSON, ločen z novimi vrsticami, na +stdout. Glasspane bere vrstico za vrstico z `BufReader`, deserializira vsako +vrstico in jo poda v `PiJsonlIngestor` (ime je podedovano — obdeluje tudi zot +dogodke). + +Bralnik teče v **eni sami nalogi ozadja na podokno** (`pane_reader_loop`). +Nikoli ne blokira glavne zanke demona — vnosnik je sinhrono zlaganje, ki +posodablja stanje podokna v pomnilniku, API posnetkov pa bere iz +`Arc>` brez sporov na vroči poti bralnika. + +Napačno oblikovane vrstice so **preskočene** s povečanjem števca, ne kot +napaka — izpadi v JSONL agenta ne smejo zrušiti opazovalca. + +**Zakaj JSONL, ne vtičnica ali gRPC**: agent je podproces, ne storitev. +stdout je univerzalni vmesnik — vsak jezik, vsaka oprema, brez nastavitve. +JSONL je trivialno pisati iz bash, Go, Python, Rust. Strukturiran žični +format bi dodal odvisnost in rokovanje vsakemu agentu. + +→ [`crates/colibri-glasspane/src/lib.rs`](../../crates/colibri-glasspane/src/lib.rs) +(`PiJsonlIngestor`, `pane_reader_loop`) + +### `AgentRuntime { Pi, Zot, Local }` — ena taksonomija za dve opremi + +Pi in zot oddajata **različne** surove vrste dogodkov: Pi uporablja +`agent_start` / `turn_end`, zot uporablja `turn_start` / `done`. Glasspane +preslika oba v iste prehode `AgentState` prek `zot_event_type()`. Enum +`AgentRuntime` označi vsako podokno z njegovo opremo, da funkcija preslikave +ve, kateri besednjak dogodkov naj razčleni. + +Polje `session_id` v strukturi `Pane` uporablja +`#[serde(alias = "pi_session_id")]` za povratno združljivost s +pred-nevtralnostnimi serializiranimi posnetki. + +**Zakaj ne dva ločena avtomata stanj**: TUI, razporejevalnik demona in +odjemalski CLI morajo vsi vprašati "v kakšnem stanju je ta agent?" — vseeno +jim je, ali je zot ali Pi. Ena taksonomija, en API. Preslikava je ~50-vrstična +funkcija, ne podsistem. + +→ [`crates/colibri-glasspane/src/lib.rs`](../../crates/colibri-glasspane/src/lib.rs) +(`zot_event_type`, `AgentRuntime`) + +### API posnetkov (bralno usmerjen, ne pisalno) + +Glasspane izpostavlja objekt posnetka (celoten nabor podoken s trenutnim +stanjem, ID seje, časovnim žigom in metapodatki) prek `Arc>`. +Demon ga streže prek svoje Unix vtičnice bralcem odjemalcev. Pisanja se +zgodijo enkrat na dogodek; branja so pogosta (pogledi TUI, statusna preverjanja +CLI). + +**Zakaj RwLock, ne kanali**: pisalna pot je nizkofrekvenčna (agentski JSONL s +hitrostjo človeškega branja), bralna pot pa v običajnem primeru brez zaklepa. +Zasnova, osnovana na kanalih, bi dodala medpomnjenje in semantiko dostave za +problem, ki je v osnovi o trenutnem stanju, ne o dostavi dogodkov. + +→ [`crates/colibri-glasspane/src/lib.rs`](../../crates/colibri-glasspane/src/lib.rs) +(`Supervisor`, `snapshot`) + +## Načrt uporabnosti (TODO) + +**Pozornostna** polovica tega načrta je dostavljena: izpeljan predikat +pozornosti, pozornostna vrstica TUI / tipke za skok / filter / poudarjanje +vrstic in robno sprožena opozorila zajema terminala. Glej +[operator-attention](./operator-attention.md) za dostavljen sistem. Kar +ostaja tukaj, je resnično nezgrajena smer. + +### Potisna obvestila navzven, ne samo na zaslonu + +Operater nadzoruje brezglave gostitelje prek Tailscale, ne z buljenjem v TUI. +Ko podokno sproži pozornost (ali doseže `Done`), jo potisni **navzven**: +namizno obvestilo na živi sliki (XFCE) in sporočilo **Telegram** (žeton je že +pripravljen). Eksplicitna pot v slogu `colibri notify` — ali vrsta dogodka +glasspane, ki jo sproži kljuka zot/Pi — omogoča agentu reči "blokiran sem", +namesto da se zanašamo samo na izpeljano stanje. Največji učinek v resničnem +svetu. + +### Bogatejše vrstice podoken (kontekst na prvi pogled) + +Glasspane že shranjuje dogodke, ki ne spreminjajo stanja, v metapodatkih +podokna. Prikaži jih v vrstici TUI: trenutni **repo/veja**, **zadnja +vrstica/povzetek naloge**, **ječa**, v kateri agent teče, neobvezno vrata za +poslušanje. Spremeni "Working" v "Working on `fix/x` v ječi `cms`, zadnje: +running tests". + +### Ohrani zgodovino podoken med ponovnimi zagoni demona + +Nadzornik je v pomnilniku (`Arc>`); ponovni zagon demona izgubi +časovnico. Ohrani prehode/zgodovino podoken, da vrnitev po urah (ali ponovnem +zagonu) ohrani "kaj se je zgodilo, ko me ni bilo". Lahka trajnost, ne nov +podsistem. + +### Odgovori blokiranemu agentu z nadzorne plošče (večji dvig) + +API posnetkov je namenoma bralno usmerjen. Prihodnja pisalna pot — "pošlji +vnos v podokno N" prek vtičnice demona — bi operaterju omogočila **odziv** +blokiranemu agentu iz `colibri-tui`, ne samo opazovanje/zagon/uboj. To je +smer, ne hitra zmaga; spremeni vtičnico iz bralnega nadzora v interaktivno +upravljanje in potrebuje lasten načrtovalski prehod. + +## Glej tudi + +- [agent-harness](./agent-harness.md) — razcep zot/Colibri, ki ga Glasspane opazuje +- [operator-attention](./operator-attention.md) — dostavljena plast pozornosti/opozoril nad tem avtomatom stanj +- [naming-decisions](./naming-decisions.md) — `pi_session_id → session_id`, `pi_type → event_type` diff --git a/docs/wiki/sl/naming-decisions.md b/docs/wiki/sl/naming-decisions.md new file mode 100644 index 0000000..60306d7 --- /dev/null +++ b/docs/wiki/sl/naming-decisions.md @@ -0,0 +1,63 @@ +--- +title: Imenik odločitev o poimenovanju +description: Živa evidenca preimenovanj, ki so jih pognale presežene predpostavke — da je prihodnji odmik preverljiv proti enemu seznamu. +--- + +← [kazalo](./index.md) + +Živa evidenca preimenovanj, ki so jih pognale presežene predpostavke, da je +prihodnji odmik preverljiv proti enemu seznamu. "Dostavljeno" pomeni združeno +v `main`; preveri proti povezani kodi, preden zaupaš vrstici. + +## Načelo poimenovanja — privzeto nevtralno glede na opremo + +Poimenuj stvar po tem, kar **je**, ne po opremi, ki je trenutno privzeta: + +- **Nevtralen koncept** (vsaka oprema ga ima — ID seje, vrsta dogodka, + samodejni zagon, "agent") → **nevtralno ime**. Oprema je _nastavljiva + vrednost_ (npr. `COLIBRI_AUTOSPAWN_BINARY=zot`), nikoli zapečena v ime in + vedno preglasljiva s strani operaterja. +- **Stvar, specifična za opremo** (dejanski žični format ene opreme) → ime + opreme sodi vanjo, vzporednice pa ostanejo simetrične (`zot_event_type` ↔ + `pi_event_type`, `AgentRuntime::{Zot, Pi}`), tako da nobena ni + privilegirana. + +Vrstice `pi_*` v [Dostavljeno](#dostavljeno) so svarilna zgodba: nevtralni +koncepti, napačno poimenovani po opremi. Enako velja za dokumentacijo — +referenca na opremo je nevtralna (`AGENT-EVENTS-REFERENCE`), ne `ZOT-…`, razen +če resnično gre samo za eno opremo. + +## Dostavljeno + +| Staro → Novo | Zakaj | Sidro | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------- | +| `COLIBRI_AUTOSPAWN_PI` → `COLIBRI_AUTOSPAWN` | Nevtralno glede na opremo (privzeti agent je zot, ne pi) | `crates/colibri-daemon/src/socket.rs` | +| `COLIBRI_PI_BINARY` → `COLIBRI_AUTOSPAWN_BINARY` | enako | `socket.rs` (`autospawn_agent_if_configured`) | +| `pi_session_id` → `session_id` | zot agenti imajo tudi ID-je sej; `#[serde(alias)]` ohranja povratno združljivost | `crates/colibri-glasspane/src/lib.rs` (`Pane`) | +| `sample-pi-agent.py` | Preimenovano iz podedovanega imena testnega agenta; oddaja konzerviran _sample_ | `scripts/sample-pi-agent.py` | +| nelokalni privzeti spawn `hermes-agent` → `zot` | `hermes-agent` je bil neobstoječ ostanek binarne datoteke | `socket.rs` (`default_agent_args`) | +| `usb_nodes` → `hive_nodes` | vozlišče je vsak gostitelj, ki se je pridružil hive, ne samo USB zagon (`+node_type`) | `packaging/mother/mother_schema.sql` | +| `pi_type` → `event_type` | notranje ime za normalizirano vrsto dogodka; nevtralno glede na opremo (ni serializirano) | `crates/colibri-glasspane/src/lib.rs` | + +## V teku + +_Trenutno nobeno._ + +## Znani ostanek (še ni ukrepan) + +| Predmet | Opomba | +| ------------------------------------ | ------------------------------------------------------------------------------------------------- | +| `ADR-agent-harness-consolidation.md` | Omenjen, vendar ne obstaja; `AGENTS.md` je pravo sidro. Glej [agent-harness](./agent-harness.md). | + +## Strukturne odločitve + +| Odločitev | Zakaj / nauk | Sidro | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| En sam dom za matično infrastrukturo = colibri | Matični MCP skripti so bili kopirani v oba colibri in clawdie-iso; kopija iso je odnesla v **SQL-injectable** `node-register-mcp` na `main`. Ista skripta v dveh repozitorijih odnese — lint prehod bi moral označiti medrepozitorijske dvojnike. | colibri `packaging/mother/`; odstranitev iso v iso PR #129 | +| `FEATURE_COLIBRI` je notranja, ni uporabniško vidna | colibri je privzeto vključen; `FEATURE_COLIBRI=NO` je izhod v sili ob gradnji (npr. brez prevzema colibri). README pojasnjen. | clawdie-iso #130 | +| `clawdie-gui` je stabilen operaterski ukaz | `clawdie-startx` ohranjen kot vzdevek za povratno združljivost (oba nameščena); dokumentacija uči `clawdie-gui`. Preverjeno namerno, ne odmik. | `clawdie-iso/README.md` §clawdie-gui; `clawdie-iso/build.sh` | + +## Glej tudi + +- [agent-harness](./agent-harness.md) +- [quality-gates](./quality-gates.md) — vrata, ki bi morala te ujeti ob času PR diff --git a/docs/wiki/sl/quality-gates.md b/docs/wiki/sl/quality-gates.md new file mode 100644 index 0000000..930dade --- /dev/null +++ b/docs/wiki/sl/quality-gates.md @@ -0,0 +1,53 @@ +--- +title: Kakovostna vrata +description: Sprememba ni "končana", dokler krajevna vrata ne uspejo — cargo fmt, clippy, cargo test, markdown vrata, wiki-lint. +--- + +← [kazalo](./index.md) + +## Odločitev + +Sprememba ni "končana", dokler krajevna vrata ne uspejo: + +```sh +./scripts/ci-checks.sh # cargo fmt --check, clippy -D warnings, cargo test, markdown gate, wiki-lint --strict +``` + +Predpotisna kljuka (`scripts/pre-push`) zažene ta ista vrata ob vsakem +`git push` na `main` — aktiviraj enkrat na klon z `./scripts/install-hooks.sh`. +Kljuka zavrne potisk, če katerakoli vrata padejo; obidi samo v sili z +`--no-verify`. + +`.forgejo/workflows/ci.yml` kodira ista preverjanja, vendar **noben izvajalnik +Forgejo Actions ni registriran**, zato nič ne uveljavlja preverjanj +strežniško. Dokler izvajalnik ni aktiven, so krajevna vrata + predpotisna +kljuka uveljavitvena plast. Navedeno kot obvezno v `AGENTS.md`. + +## Zakaj ta stran obstaja + +Napaka pri prevajanju (`pi_binary` nedefiniran, iz napol dokončanega +preimenovanja) je dosegla `main`, ker so bila vrata preskočena _in_ +neuveljavljena. Ista revizija je ugotovila, da so bila oboja vrata takrat +dejansko rdeča na `main`: + +- `clippy -D warnings` je padel na predobstoječem lintu → Rust vrata bi + padla za vsakogar, ki bi jih zagnal. +- markdown vrata so padla na prettier-umazanih dokumentih. + +Oboje je bilo spravljeno v zeleno, zato so vrata zdaj dejansko zagonljiva. +Nauk: vrata, ki jih nihče ne poganja (in so tako ali tako rdeča), so +korenski vzrok, da odmik doseže `main` — bolj kot vsak posamezen spodrsljaj +pri poimenovanju. + +## Odnos do tega wikija + +Imenik [naming-decisions](./naming-decisions.md) + `wiki-lint --strict` sta +_pomenska_ protiutež `ci-checks.sh`: prevajalnik/clippy ujameta zlomljeno +_kodo_, ne pa dokumenta, ki še vedno opisuje staro zasnovo, ali imena, ki je +odneslo. Wiki lint pokriva to vrzel. Zdaj je del obveznih vrat — napaka +odmika blokira potisk, enako kot opozorilo clippy. + +## Glej tudi + +- [agent-harness](./agent-harness.md) +- [naming-decisions](./naming-decisions.md) diff --git a/docs/wiki/sl/store-schema.md b/docs/wiki/sl/store-schema.md new file mode 100644 index 0000000..022fb67 --- /dev/null +++ b/docs/wiki/sl/store-schema.md @@ -0,0 +1,145 @@ +--- +title: Shema shrambe +description: Koordinacijska shramba Colibri — ena sama podatkovna zbirka SQLite, ki hrani tablo opravil, register agentov in veščin ter preslikavo najemnikov. +--- + +← [kazalo](./index.md) + +Colibrijeva koordinacijska shramba je ena sama podatkovna zbirka SQLite v +lasti storitve `colibri`. Hrani tablo opravil, register agentov in veščin ter +preslikavo najemnikov trezorja. Ni predpomnilnik — je trajno stanje. Večina +pisanj gre skozi API vtičnice demona, vendar shema pripada `colibri-store`. + +→ `crates/colibri-store/src/schema.rs` + +→ `crates/colibri-store/src/lib.rs` + +## Odločitve + +### SQLite, ne PostgreSQL, za shrambo krmilne ravnine + +Shramba je SQLite, ker krmilna ravnina potrebuje enodatotečno podatkovno +zbirko, ki jo je enostavno varnostno kopirati, posneti, pregledati in +odpremiti. PostgreSQL s pgvector je načrtovan za iskanje/dolgoročni spomin, +vendar tabla opravil in register agentov ne potrebujeta strežniškega procesa. + +Demon paketno združuje povezana pisanja in se zanaša na način WAL v SQLite za +sočasne bralce. To ohranja operaterski sklad samozadosten na majhnem +gostitelju brez diska. + +### WAL + tuji ključi privzeto + +`Store::open` ob vsakem zagonu zažene tri pragme: + +- `journal_mode=WAL` — bralci ne blokirajo piscev. +- `synchronous=NORMAL` — varna sredina med polno-sinhronim in OFF. +- `foreign_keys=ON` — FK opravilo/agent je uveljavljen. + +Te niso nastavljive med izvajanjem. Če bomo kdaj potrebovali drugačna jamstva +glede trajnosti ali sočasnosti, naj bo to eksplicitno, namesto da bi povezava +podedovala privzetke. + +→ `crates/colibri-store/src/lib.rs` (`Store::open`) + +### Samo idempotentne migracije + +Migracije tečejo ob vsakem `Store::open`. Uporabljajo tabele in indekse +`IF NOT EXISTS`, tako da so ponovni teki varni. Ne odpremljamo migracij +navzdol; razvoj sheme so aditivne tabele in stolpci. Če bo kdaj potrebna +destruktivna migracija, mora biti to nameren ročni korak, dokumentiran v +predaji. + +→ `crates/colibri-store/src/schema.rs` + +### Štiri tabele za štiri skrbi + +| Tabela | Skrb | Ključna entiteta | +| --------- | ------------------------------ | ---------------- | +| `tasks` | Tabla opravil | `Task` | +| `agents` | Registrirani sodelavci | `Agent` | +| `skills` | Katalog veščin ekipe | `Skill` | +| `tenants` | Preslikava najemnikov/trezorja | `Tenant` | + +Opravila nosijo tuji ključ `agent_id` v `agents`. Vsako drugo razmerje je +ohlapno — veščine niso povezane z agenti, najemniki pa so referencirani po +svojem `tenant_id` v ukazih vtičnice in kljukah za oskrbo. + +→ `crates/colibri-store/src/schema.rs` + +### Omejitev CHECK stanja opravila je vir resnice + +`tasks.status` je omejen na `('queued','claimed','started','done','failed')`. +Enum `TaskStatus` v Rustu ga zrcali, vendar je podatkovna zbirka zadnja +vrata. Ukaz, ki poskusi vstaviti neznano stanje, pade ob času pisanja. + +→ `crates/colibri-store/src/schema.rs` + +### Zmožnosti agenta shranjene kot JSON, ne normalizirane + +`agents.capabilities` je JSON blob, na primer +`["code","rust","freebsd"]`. Izognili smo se ločeni tabeli zmožnosti, ker so +oznake zmožnosti samo nizi, register ekipe pa je majhen. Normalizirani stiki +bi dodali zapletenost sheme brez izboljšanja moči poizvedb. + +Če metapodatki zmožnosti zrastejo (uteži, različice, zahtevane veščine), +lahko to kasneje razcepimo; trenutna shema namenoma ostaja pragmatična. + +→ `crates/colibri-store/src/lib.rs` (`register_agent`) + +### Najemniki kodirajo preslikavo 1:1:1 ječa/trezor/zbirka + +`tenants` hrani `tenant_id`, `jail_root_path` in `collection_id` kot UNIQUE +stolpce. Pravilo je `tenant_id = ime ječe = zbirka Vaultwarden`. To omogoča +`colibri-vault`, da poišče ječo po imenu in natančno ve, katero pot +gostitelja in zbirko Vaultwarden uporabiti pri pisanju datoteke okolja. + +Stolpec `status` najemnika sledi življenjskemu ciklu: +`provisioned → active → stopped → destroyed`. Neodvisen je od tega, ali +proces ječe teče; upravljanje življenjskega cikla je ločena skrb. + +→ `crates/colibri-store/src/schema.rs` (komentarji na `tenants`) + +### Privzeta pot podatkovne zbirke je specifična za platformo + +Privzetek shrambe je: + +- `COLIBRI_DB_PATH`, če je nastavljeno. +- FreeBSD: `/var/db/colibri/colibri.sqlite`. +- Linux/macOS: `$XDG_DATA_HOME/colibri/colibri.sqlite`, s padcem na + `$HOME/.local/share/colibri/colibri.sqlite`, nato `/tmp`. + +FreeBSD privzeto uporablja `/var/db`, ker je to običajni imenik za krajevno +stanje storitev. Linuxov padec spoštuje XDG, tako da je razvoj na delovni +postaji normalen. + +→ `crates/colibri-store/src/lib.rs` (`default_db_path`) + +### Izvoz JSON za varnostne kopije in paritetne teste + +`Store::export_json()` izvozi vse štiri tabele v en objekt JSON. Obstaja za +paritetne dife dvojnega teka, priložnostne varnostne kopije in razhroščevanje. +Ni primarni poizvedovalni API; večina bralcev naj uporablja tipizirane metode. + +## Razmerja entitet + +```text +tasks.agent_id ----------> agents.id + + tasks agents skills tenants + ----- ------ ------ ------- + id id id tenant_id + agent_id FK name name jail_root_path + status capabilities description collection_id + title status category status + description created_at created_at created_at + created_at updated_at + updated_at +``` + +## Glej tudi + +- [task-board](./task-board.md) — življenjski cikel opravila in ujemanje zmožnosti +- [operator-cli](./operator-cli.md) — ukazi vtičnice, ki pišejo v te tabele +- [vault-provision](./vault-provision.md) — kako tabela najemnikov poganja oskrbo datotek env +- [jail-confinement](./jail-confinement.md) — imena ječ se preslikajo v vrstice najemnikov +- [skills-catalog](./skills-catalog.md) — bralni porabnik veščin -- 2.45.3 From 8f84eb51c2c0773570eb441bf37f35ee1807d2ca Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:05:32 +0200 Subject: [PATCH 04/19] =?UTF-8?q?docs(sl):=20translate=20wiki=20group=202?= =?UTF-8?q?=20=E2=80=94=20deployment,=20operator-cli,=20terminal,=20tui,?= =?UTF-8?q?=20headroom-sidecar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/wiki/sl/deployment.md | 171 +++++++++++++++++++++++++++++++ docs/wiki/sl/headroom-sidecar.md | 49 +++++++++ docs/wiki/sl/operator-cli.md | 62 +++++++++++ docs/wiki/sl/terminal.md | 49 +++++++++ docs/wiki/sl/tui.md | 56 ++++++++++ 5 files changed, 387 insertions(+) create mode 100644 docs/wiki/sl/deployment.md create mode 100644 docs/wiki/sl/headroom-sidecar.md create mode 100644 docs/wiki/sl/operator-cli.md create mode 100644 docs/wiki/sl/terminal.md create mode 100644 docs/wiki/sl/tui.md diff --git a/docs/wiki/sl/deployment.md b/docs/wiki/sl/deployment.md new file mode 100644 index 0000000..cf29329 --- /dev/null +++ b/docs/wiki/sl/deployment.md @@ -0,0 +1,171 @@ +--- +title: Namestitev +description: Nameščevalnik gostitelja clawdie — odkrije ZFS, pripravi podatkovne zbirke, ustvari uporabnika storitve in namesti enoto rc.d/systemd. +--- + +← [kazalo](./index.md) + +Zaboj `clawdie` je Colibrijev nameščevalnik gostitelja. Odkrije postavitev +ZFS na napravi in pripravi storitev `clawdie`. Na FreeBSD to pomeni storitev +rc.d, podatkovne zbirke ZFS in neprivilegiranega uporabnika. Na Linuxu lahko +uporablja systemd in bodisi ZFS bodisi navadne imenike. + +→ `crates/clawdie/src/main.rs` | `crates/clawdie/src/plan.rs` +→ `docs/ISO-SERVICE-LAYOUT.md` | `docs/CLAWDIE-INSTALLER-HANDOFF.md` + +## Odločitve + +### ZFS je obvezen na FreeBSD, priporočen na Linuxu + +FreeBSD ne podpira postavitve z navadnimi imeniki. Če ZFS uporabniški prostor +manjka, načrt takoj sporoči napako. Linux lahko pade na navadne imenike, če +ni imenovan noben bazen in ZFS ni na voljo, na zahtevo pa lahko ustvari svež +bazen na prostem disku. + +To ustreza produkcijskemu cilju: goli FreeBSD na zrcalnem polju ZFS RAID1. +Podpora za Linux omogoča razvoj in CI brez gostitelja ZFS. + +### Shramba je razrešena, ne nastavljena + +`clawdie plan` razreši shrambo v tem vrstnem redu: + +1. Če je podano `--pool NAME --create-pool DEVICE`, ustvari ta bazen. +2. Če je podano `--pool NAME`, uporabi ta obstoječi bazen. +3. Če ni podan noben bazen in obstaja natanko en bazen, ga uporabi. +4. Če obstaja več bazenov in noben ni imenovan, napaka. +5. Na Linuxu brez ZFS padec na navadne imenike. + +To odpravlja potrebo po ročno napisani topološki datoteki na tipičnih +enobazenskih gostiteljih, hkrati pa omogoča ekspliciten nadzor, ko je +potreben. + +→ `crates/clawdie/src/main.rs` (`pick_pool`, `validate_storage`) + +### Podatkovne zbirke ločujejo stanje od dnevnikov + +Ko je ZFS uporabljen, nameščevalnik ustvari: + +- `/clawdie` kot vsebniško podatkovno zbirko z `canmount=off` +- `/clawdie/db` priklopljeno na `/var/db/clawdie` +- `/clawdie/log` priklopljeno na `/var/log/clawdie` + +Hramba podatkovne zbirke in dnevnikov v ločenih podatkovnih zbirkah omogoča, +da posnetki, kvote in pravilniki vrtenja dnevnikov veljajo neodvisno. + +→ `crates/clawdie/src/plan.rs` (`zfs_dataset_steps`) + +### Privzeto suhi tek + +`clawdie apply` izpiše načrt in konča, razen če je podano `--yes`. `discover` +in `plan` sta samo za branje. To ščiti produkcijske gostitelje pred nenamernim +pripravljanjem. + +→ `crates/clawdie/src/main.rs` (`Cmd::Apply`) + +### Ustvarjanje bazena je varovano pred zasedenimi diski + +`--create-pool` na nepraznem disku je zavrnjeno, razen če je podano tudi +`--force`. Nameščevalnik uporablja `lsblk` na Linuxu za zaznavanje particij, +datotečnih sistemov, priklopnih točk in korenskega diska. Varovalo je +konzervativno: če je disk dvoumen, ga je treba eksplicitno vsiliti. + +→ `crates/clawdie/src/disk.rs` | `crates/clawdie/src/main.rs` (`validate_create_device`) + +### En sam neprivilegiran uporabnik storitve + +Storitev teče kot `_clawdie` na obeh platformah. Na FreeBSD je uporabnik +ustvarjen z `pw useradd -s /usr/sbin/nologin -d /var/db/clawdie`, izhodna koda +`65` (že obstaja) pa se obravnava kot preskok. Na Linuxu se uporabi `useradd +--system`. Imeniki stanja se nato chownajo temu uporabniku. + +→ `crates/clawdie/src/platform.rs` + +### Upravitelji storitev, specifični za platformo, ista specifikacija + +`Platform` je notranji trait. Izvedbi se razlikujeta samo v tem, kako +namestita in omogočita enoto: + +- FreeBSD: zapiše `/usr/local/etc/rc.d/clawdie`, uporabi `sysrc clawdie_enable=YES`. +- Linux: zapiše `/etc/systemd/system/clawdie.service`, zažene `systemctl enable --now clawdie`. + +Obe uporabljata isto `ServiceSpec` (binarna datoteka, uporabnik, podatkovni +imenik, ime storitve). Zagon `apply` na različnih platformah zato ustvari +enako postavitev datotečnega sistema in se razlikuje samo v ovoju upravitelja +storitev. + +→ `crates/clawdie/src/platform.rs` (`FreeBsd`, `Linux`) + +### Demon teče skozi nadzornika platforme + +Ustvarjeni skript rc.d za FreeBSD izvede `/usr/local/bin/colibri-daemon` skozi +`/usr/sbin/daemon -u _clawdie`, tako da nadzornik ob zrušitvi ponovno zažene +in proces pade na neprivilegiranega uporabnika. Enota systemd je preprosta +storitev z `Restart=on-failure`. + +Nameščevalnik sam ne zažene demona ali ne pripravi binarne datoteke; samo +ustvari okolje. Operater ali paketna gradnja pripravi `colibri-daemon` in nato +`service clawdie start`. + +→ `docs/ISO-SERVICE-LAYOUT.md` (rc.d prek daemon(8)) + +### Skrivnosti ne piše nameščevalnik + +Nameščevalnik se ne dotika ključev API ponudnika. Ločena datoteka — običajno +`/usr/local/etc/colibri/provider` — hrani skrivnosti in jo pred zagonom +demona prebere rc.d. To ohranja domet nameščevalnika omejen na ZFS, imenike, +uporabnike in datoteke storitev. + +→ [vault-provision](./vault-provision.md) + +### Koraki se izvajajo zaporedno in se ustavijo ob napaki + +`deploy::apply` zažene vsak `Step` po vrsti. Koraki `Run` pokličejo lupino in +padejo ob neničelnem izhodu, razen če korak navede dovoljene izhodne kode. +Koraki `WriteFile` ustvarijo starševske imenike, zapišejo datoteko in jo +chmodajo. Če katerikoli korak pade, se apply takoj ustavi in sporoči ukaz, ki +je padel, ter stderr. + +→ `crates/clawdie/src/deploy.rs` + +## Oblika načrta + +```text +clawdie plan + ├── ZFS layout (ali navadni imeniki) + │ ├── create /clawdie container + │ ├── create /clawdie/db -> /var/db/clawdie + │ └── create /clawdie/log -> /var/log/clawdie + └── service install + ├── create user _clawdie + ├── chown state dirs + ├── write service unit (rc.d / systemd) + ├── enable service (sysrc / systemctl) + └── [systemd] daemon-reload + start +``` + +## Tipična namestitev FreeBSD + +```sh +# odkrij +clawdie discover + +# predogled +clawdie plan + +# pripravi podatkovne zbirke, uporabnika in storitev rc.d +sudo clawdie apply --yes + +# zaženi, ko je binarna datoteka colibri-daemon pripravljena +sudo service clawdie start +``` + +## Navzkrižne povezave na izvajalne poti + +Po namestitvi ima storitev te poti: + +- `/var/db/clawdie/colibri.sqlite` — koordinacijska shramba SQLite +- `/var/run/clawdie/clawdie.sock` — Unix vtičnica demona +- `/var/log/clawdie/daemon.log` — dnevnik stdout/stderr +- `/usr/local/etc/colibri/` — konfiguracija in skrivnosti ponudnika + +→ [store-schema](./store-schema.md) | [operator-cli](./operator-cli.md) diff --git a/docs/wiki/sl/headroom-sidecar.md b/docs/wiki/sl/headroom-sidecar.md new file mode 100644 index 0000000..bd45985 --- /dev/null +++ b/docs/wiki/sl/headroom-sidecar.md @@ -0,0 +1,49 @@ +--- +title: Stranski vagon Headroom +description: Colibri lahko neobvezno prosi krajevni stranski vagon headroom-ai, da stisne rezultate orodij, preden dosežejo proračun žetonov. +--- + +← [kazalo](./index.md) + +Colibri lahko neobvezno prosi krajevni stranski vagon `headroom-ai`, da stisne +rezultate orodij, preden dosežejo proračun žetonov. Je ločen proces Python, ki +posluša na drugi vtičnici Unix, in je privzeto izklopljen. + +→ `crates/colibri-daemon/src/session.rs` (klicatelj) +→ `headroom-ai/` (izvedba stranskega vagona) + +## Odločitve + +### Kompresija, gnana s proračunom, ne vedno vklopljena + +Stranski vagon se pokliče samo, ko seja tvega, da bo presegla svoj proračun +— ne ob vsakem rezultatu orodja. Sprožilec je prag v sledilcu stroškov: če +bi naslednji korak presegel proračun, najprej stisni, nato obreži. Brez +stranskega vagona je zasilni izhod preprosto krajšanje. + +→ [cost-model](./cost-model.md) (stiskanje T14) + +### Unix vtičnica, ne HTTP + +Komunikacija poteka prek druge vtičnice Unix (`/var/run/headroom/headroom.sock`). +Stranski vagon sprejme surovo besedilo, vrne povzetek. Brez avtentikacije — +zaupa meji vtičnice Unix in temu, da oba procesa tečeta kot isti uporabnik. + +### Enostaven protokol — besedilo noter, besedilo ven + +Stranski vagon prejme eno vrstico JSON `{"text": "..."}`, vrne eno vrstico +JSON `{"summary": "..."}`. Brez sej, brez konteksta, brez zgodovine. Vsak +klic je brez stanja. + +### Ločen proces, ne knjižnica + +Stranski vagon teče kot neodvisen proces Python, ne kot uvoz Rust. To ga +izolira od zrušitev (če stranski vagon pade, demon nadaljuje brez njega), +izolira njegov pomnilnik (model Python je lačen) in omogoča neodvisno +posodabljanje. + +→ `headroom-ai/src/server.py` + +## Glej tudi + +- [cost-model](./cost-model.md) — kdaj se sproži stranski vagon diff --git a/docs/wiki/sl/operator-cli.md b/docs/wiki/sl/operator-cli.md new file mode 100644 index 0000000..0bfb0a9 --- /dev/null +++ b/docs/wiki/sl/operator-cli.md @@ -0,0 +1,62 @@ +--- +title: Operaterski CLI (`colibri`) +description: Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona — tanek tipiziran odjemalec Unix vtičnice. +--- + +← [kazalo](./index.md) + +Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona. +Je tanek odjemalec — pošilja ukaze JSON po vtičnici Unix, razčlenjuje odgovore +in jih izpisuje. Vsak podukaz CLI se preslika v en ukaz demona. Vmesnik CLI +dodaja priročnost (barvni izpis, privzetki, oblikovalci), ne poslovne logike. + +→ `crates/colibri-client/src/bin/colibri.rs` + +## Odločitve + +### Ena binarna datoteka, ena vtičnica + +Obstaja ena binarna datoteka `colibri`, ki se poveže na eno vtičnico +(`/var/run/colibri/colibri.sock` ali `COLIBRI_SOCKET`). Ni podukazov za +izbiro demona — večgostiteljske operacije gredo skozi most krmilne ravnine. +Operater izrecno usmeri na drug gostitelj (`nc 9190`), ne da bi +CLI podpiral več končnih točk. + +**Zakaj ne več profilov demona**: en demon na gostitelja je zadosten. Več +končnih točk bi v CLI vneslo stanje (`colibri --host osa status`), ki ga most +že rešuje na omrežni plasti. + +### CLI je generičen odjemalec JSON-RPC + +Vsak podukaz zgradi objekt `ColibriCommand`, pokliče +`client.request(command).await` in izpiše rezultat. Odjemalec ne ve ničesar o +pomenu kateregakoli ukaza — samo serializira in razčlenjuje. + +Oblikovalci izhodov (`print_json`, `print_table`, `print_key_value`) so čiste +funkcije nad `serde_json::Value`. Če demon doda novo polje, se samodejno +prikaže v izhodu JSON brez spremembe v CLI. + +### En ukaz na zagon, ne interaktivno + +Vsak zagon `colibri` izvede natanko en ukaz in konča. Brez lupine REPL, brez +več ukazov v eni seji. To ohranja CLI brez stanja in varnega za skriptanje: +`colibri status | jq '.data.agents'` je enako zanesljiv v cronu kot v +terminalu. + +→ `crates/colibri-client/src/bin/colibri.rs` (`main`) + +### Podukazi, specifični za tablo opravil, sledijo istemu vzorcu + +Ukazi za opravila (`create-task`, `intake-task`, `claim-task`, +`transition-task`) sprejemajo argumente CLI, ki se preslikajo v polja ukaza +JSON. Izhod je bodisi celoten objekt opravila (za `create-task`, +`intake-task`) bodisi potrditev (`claim-task`, `transition-task`). Noben +podukaz ne zahteva več kot ~3 argumentov — opravilna tabla je namenjena +dodeljevanju s strani agenta, ne ročnemu upravljanju. + +→ `crates/colibri-client/src/bin/colibri.rs` + +## Glej tudi + +- [task-board](./task-board.md) — ukazi, ki jih CLI zrcali +- [deployment](./deployment.md) — kako je nameščena binarna datoteka demona diff --git a/docs/wiki/sl/terminal.md b/docs/wiki/sl/terminal.md new file mode 100644 index 0000000..572d9e7 --- /dev/null +++ b/docs/wiki/sl/terminal.md @@ -0,0 +1,49 @@ +--- +title: Terminal — zmožnost, ne znamka +description: Zmožnost terminala kot ozka, prenosljiva abstrakcija — Kitty, ne iTerm2; ANSI, ne lastniški protokoli. +--- + +← [kazalo](./index.md) + +Colibrijeva zmožnost terminala je namenoma ozka: zajemi zaslon tmux, pošlji +tipke, beri izhod. Ne vključuje večpredstavnosti, brskalnika ali obogatenega +besedila. Izbira terminalskega odjemalca temelji na enem kriteriju: ali +protokol podpira **razširjeno poročanje tipk**, tako da lahko Glasspane +razlikuje `Enter` od `Ctrl+Enter`? + +## Odločitve + +### Kitty kot terminalski odjemalec (protokol, ne GUI) + +Colibri cilja na terminalski odjemalec Kitty zaradi njegovega protokola +razširjenega poročanja tipk — brez tega Glasspane ne more razlikovati +modifikatorskih tipk (`Ctrl+Enter` proti `Enter`), ne da bi zajel vnosno +plast. To ni predpis GUI — vsak terminalski odjemalec, ki izvaja protokol +Kitty (WezTerm, foot, Ghostty), deluje enako dobro. + +### tmux kot terminalski multiplekser (ne alternativni terminal) + +Agentske seje se izvajajo znotraj sej tmux, ker tmux zagotavlja obstojnost +seje (preživi odklop), več oken na agenta in programski vmesnik `capture-pane`, +ki ga Glasspane uporablja za zajem terminala. Tmux se vstavi med terminalski +odjemalec in agenta, ne nadomesti terminalskega odjemalca. + +### SSH terminfo — `tmux-256color`, ne `xterm-256color` + +`tmux-256color` je edina vrednost `TERM`, podprta za SSH povezave do agentov. +Ne podpira `xterm-256color`, ker zunaj tmux ta vrednost ne more poročati +razširjenih zaporedij Kitty. Terminfo se uveljavi v zanki demona za vse +povezave. + +### ANSI, ne lastniški — vendar s prehodom Kitty + +Izhod agenta uporablja ANSI ubežna zaporedja za barve in pozicioniranje +kazalke. To je univerzalno. Edina razširitev onkraj ANSI je stiskanje vnosa +tipk, kjer Glasspane potrebuje protokol Kitty za razlikovanje modifikatorjev. + +→ `crates/colibri-daemon/src/terminal.rs` + +## Glej tudi + +- [tui](./tui.md) — nadzorna plošča TUI, ki se upodablja v tem terminalu +- [operator-attention](./operator-attention.md) — zajem terminala kot signal diff --git a/docs/wiki/sl/tui.md b/docs/wiki/sl/tui.md new file mode 100644 index 0000000..9966637 --- /dev/null +++ b/docs/wiki/sl/tui.md @@ -0,0 +1,56 @@ +--- +title: Terminalska nadzorna plošča (colibri-tui) +description: Colibrijeva živa terminalska nadzorna plošča — povezuje se na Unix vtičnico demona in prikazuje agente, stanja ter pozornostna opozorila. +--- + +← [kazalo](./index.md) + +TUI je Colibrijeva živa terminalska nadzorna plošča. Poveže se na Unix +vtičnico demona, poizveduje API posnetkov (`glasspane-snapshot`) in ga +upodablja kot tabelo podoken s stanjem. Zgrajena z ratatui + crossterm za +barvni terminalski izhod. + +→ `crates/colibri-glasspane-tui/src/main.rs` + +## Odločitve + +### En zaslon, en pogled — ni navigacije po zavihkih + +TUI upodablja eno glavno tabelo s podokni in neobvezno pozornostno vrstico na +vrhu. Brez zavihkov, brez stranskih plošč, brez oken. Operater filtrira z +vnosom s tipkami (`/` za sejo, `a` za pozornost), ne s klikanjem. + +### Razporeditev glede na stanje + +Vsako podokno dobi barvo glede na `AgentState`: zelena (Working), rumena +(Blocked), modra (Done), rdeča (Error), siva (Idle). Podokna z napako že +prikazujejo rdeče besedilo. Pozornostna vrstica, tipke za skok in filter +dodajajo rdečo obrobo in inverzno ozadje na vrstice, ki potrebujejo pozornost. + +→ [operator-attention](./operator-attention.md) + +### Enovrstične vrstice podoken po meri agentov + +Vsaka vrstica podokna vsebuje: ime agenta, stanje, ID seje (skrajšan), +časovni žig zadnjega dogodka in zastavico stalled. To je minimalen nabor, ki +ga operater potrebuje za oceno agenta na prvi pogled. Prihodnje delo: površina +metapodatkov podokna za bogatejše vrstice. + +### Osveževanje — poizvedovanje, ne potiskanje + +TUI poizveduje demonov API posnetkov (`glasspane-snapshot`) vsakih 250 ms. +Brez WebSocket, brez SSE, brez potisnih obvestil med TUI in demonom. +Poizvedovanje ohranja vtičnico demona brez stanja. + +### Barve so nosilne + +`NO_COLOR=1`, ki uhaja iz sej Hermesa, bi naredil TUI neberljiv brez barv. +`main()` vsili `crossterm::style::force_color_output(true)`, da to prepreči. +To je nadzorna plošča, ne orodje za cevovod. + +→ `crates/colibri-glasspane-tui/src/main.rs` + +## Glej tudi + +- [glasspane](./glasspane.md) — avtomat stanj, ki ga TUI upodablja +- [operator-attention](./operator-attention.md) — pozornostna vrstica in tipke za skok -- 2.45.3 From 9fd323b092ebb9359a91eedeae0a98657e5f60a5 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:08:02 +0200 Subject: [PATCH 05/19] =?UTF-8?q?docs(sl):=20translate=20wiki=20group=203?= =?UTF-8?q?=20=E2=80=94=20runtime-inventory,=20jail-confinement,=20skills-?= =?UTF-8?q?catalog,=20vault-provision,=20agent-events-reference,=20externa?= =?UTF-8?q?l-mcp?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes Slovenian wiki translation: all 23 pages now have sl/ mirrors. --- docs/wiki/sl/agent-events-reference.md | 63 +++++++++++++++++++++++ docs/wiki/sl/external-mcp.md | 69 ++++++++++++++++++++++++++ docs/wiki/sl/jail-confinement.md | 44 ++++++++++++++++ docs/wiki/sl/runtime-inventory.md | 48 ++++++++++++++++++ docs/wiki/sl/skills-catalog.md | 45 +++++++++++++++++ docs/wiki/sl/vault-provision.md | 49 ++++++++++++++++++ 6 files changed, 318 insertions(+) create mode 100644 docs/wiki/sl/agent-events-reference.md create mode 100644 docs/wiki/sl/external-mcp.md create mode 100644 docs/wiki/sl/jail-confinement.md create mode 100644 docs/wiki/sl/runtime-inventory.md create mode 100644 docs/wiki/sl/skills-catalog.md create mode 100644 docs/wiki/sl/vault-provision.md diff --git a/docs/wiki/sl/agent-events-reference.md b/docs/wiki/sl/agent-events-reference.md new file mode 100644 index 0000000..1fc9a56 --- /dev/null +++ b/docs/wiki/sl/agent-events-reference.md @@ -0,0 +1,63 @@ +--- +title: Referenca agentskih dogodkov +description: Referenca dogodkov po opremi za zot in pi, preslikave Glasspane in preverjena polja prepisa. +--- + +← [kazalo](./index.md) + +Ta stran je kanonična referenca za vse vrste dogodkov JSONL, ki jih oddajata +zot in pi. Vsaka vrstica je en dogodek; vsak dogodek ima znano shemo. Glasspane +uporablja te preslikave za pretvorbo surovih dogodkov v prehode `AgentState`. + +## Skupna polja (vsi dogodki) + +Vsak agentski dogodek JSONL vsebuje ta polja: + +| Polje | Tip | Opis | +| ------------ | --- | ---------------------------------------------- | +| `event` | niz | Vrsta dogodka (npr. `agent_start`, `turn_end`) | +| `timestamp` | niz | Časovni žig ISO 8601 | +| `session_id` | niz | ID seje agenta | + +## Dogodki zot + +| Dogodek | Sprožilec | Preslikava Glasspane | +| ------------- | ------------------------------ | --------------------------------- | +| `turn_start` | Agent začne obdelovati korak | `Working` | +| `tool_call` | Agent pokliče orodje | (metapodatki, ne spremeni stanja) | +| `tool_result` | Orodje vrne rezultat | (metapodatki) | +| `done` | Agent konča korak uspešno | `Done` | +| `error` | Agent naleti na napako | `Error` | +| `blocked` | Agent čaka na operaterski vnos | `Blocked` | +| `agent_start` | Zagon agenta | `Working` | +| `usage` | Poročilo o uporabi žetonov | (metapodatki) | + +## Dogodki pi + +| Dogodek | Sprožilec | Preslikava Glasspane | +| -------------- | ------------------------------ | -------------------- | +| `agent_start` | Zagon agenta | `Working` | +| `turn_end` | Agent konča korak | `Done` | +| `agent_error` | Agent naleti na napako | `Error` | +| `blocked` | Agent čaka na operaterski vnos | `Blocked` | +| `usage_report` | Poročilo o uporabi žetonov | (metapodatki) | + +## Preverjena polja prepisa + +Ta polja so se pojavila v resničnem izhodu zot in so potrjena kot prisotna: + +| Polje | Vir | Opomba | +| ------------ | --- | ------------------------------------- | +| `turn_id` | zot | Enolični ID koraka | +| `model` | zot | Ime modela, uporabljenega za ta korak | +| `tokens_in` | zot | Število vhodnih žetonov | +| `tokens_out` | zot | Število izhodnih žetonov | +| `tool_name` | oba | Ime orodja, ki ga je agent poklical | + +→ `crates/colibri-glasspane/src/lib.rs` (`zot_event_type`, `PiJsonlIngestor`) +→ `crates/colibri-daemon/tests/zot_rpc_smoke.rs` + +## Glej tudi + +- [glasspane](./glasspane.md) — kako se dogodki preslikajo v stanja +- [agent-harness](./agent-harness.md) — razcep zot/Colibri diff --git a/docs/wiki/sl/external-mcp.md b/docs/wiki/sl/external-mcp.md new file mode 100644 index 0000000..0a9cc39 --- /dev/null +++ b/docs/wiki/sl/external-mcp.md @@ -0,0 +1,69 @@ +--- +title: Zunanji MCP +description: Most MCP za urejevalnike in zunanje gostitelje — branje, pisanje in vrata za zunanje klice prek Colibrijeve implementacije MCP. +--- + +← [kazalo](./index.md) + +Colibri izpostavlja podmnožico svoje krmilne ravnine kot strežnik MCP +(Model Context Protocol), tako da lahko zunanji urejevalniki (VS Code, +Zed), agentski okviri (Claude Code, Hermes) in skripte komunicirajo z +Colibrijem prek standardiziranega protokola. + +→ `crates/colibri-mcp/src/lib.rs` + +## Odločitve + +### stdio, ne HTTP + +Strežnik MCP komunicira prek standardnega vhoda/izhoda (stdio), ne prek +HTTP ali WebSocket. To je standardni prenos MCP — vsak odjemalec MCP ga +podpira. Prav tako se izogne potrebi po odprtju drugega omrežnega vmesnika. + +### Tri orodja, ne celoten API + +Strežnik MCP izpostavlja tri orodja: + +| Orodje | Ukaz demona | Namen | +| ------------------ | -------------------- | ----------------------------------------------- | +| `colibri_status` | `status` | Stanje demona (agenti, opravila, predpomnilnik) | +| `colibri_snapshot` | `glasspane-snapshot` | Trenutni posnetek podoken Glasspane | +| `colibri_spawn` | `spawn-agent` | Zaženi novega agenta | + +Ta tri orodja pokrivajo 90 % zunanjih interakcij. Celoten API vtičnice je na +voljo neposrednim odjemalcem vtičnice; MCP je priročna podmnožica. + +### Ovoj Bash, ne vgrajeni proces + +`colibri-mcp` je skripta Bash, ki se poveže na vtičnico demona, pošlje ukaz +JSON in vrne odgovor JSON. Ni dolgotrajen proces — vsak klic zažene novo +skripto. To pomeni, da je ničelna konfiguracija za odjemalce MCP (samo +registrirajte pot skripte) in ničelno vzdrževanje stanja. + +→ `packaging/freebsd/colibri-mcp` + +### Vrata za branje/pisanje in zunanje klice + +Implementacija MCP ločuje tri skrbi: + +- **Branje**: `status`, `snapshot` — samo za branje, vedno na voljo. +- **Pisanje**: `spawn` — spremeni stanje demona. Zaščiteno z zastavico + `allow_write` v konfiguraciji MCP. +- **Zunanji klic**: katerokoli orodje lahko sproži verigo MCP, ki sega + navzven do drugega strežnika MCP. Zaščiteno z zastavico `allow_external_call`. + +→ `crates/colibri-mcp/src/config.rs` + +### Inicializacijski manifest ob zagonu + +Vsak strežnik MCP mora ob zagonu vrniti manifest `initialize`. Colibrijev +manifest deklarira svoja tri orodja, zmogljivost `tools` in prazno +zmogljivost `resources`. Odjemalci, ki ne pokličejo `initialize`, dobijo +napako protokola. + +→ `crates/colibri-mcp/src/protocol.rs` (`initialize`) + +## Glej tudi + +- [mother-hive](./mother-hive.md) — MCP prek SSH za matično vozlišče +- [operator-cli](./operator-cli.md) — neposreden dostop do vtičnice diff --git a/docs/wiki/sl/jail-confinement.md b/docs/wiki/sl/jail-confinement.md new file mode 100644 index 0000000..7bfd6ce --- /dev/null +++ b/docs/wiki/sl/jail-confinement.md @@ -0,0 +1,44 @@ +--- +title: Omejitev ječ +description: Trajne proti prehodnim ječam, pravilnik načina priv in ponovna uporaba omejitve zaganjalnika za strežnike MCP. +--- + +← [kazalo](./index.md) + +Colibrijevi agenti tečejo znotraj ječ FreeBSD Bastille. Model omejitve je +zasnovan tako, da so vse agentske interakcije privzeto zaprte, izrecne +priklopne točke pa namerne. + +→ `packaging/freebsd/bastille/` + +## Odločitve + +### Trajne ječe za agente, prehodne za MCP + +Agenti tečejo v **trajnih** ječah (eni na agenta), ki preživijo ponovne +zagone. Te ječe imajo stanje: nameščene pakete, konfiguracijske datoteke, +klonirane repozitorije. Strežniki MCP tečejo v **prehodnih** ječah, ustvarjenih +iz iste predloge, a uničenih, ko se seja MCP konča. Prehodne ječe se začnejo +sveže — brez stanja, brez ostankov. + +→ `crates/colibri-daemon/src/spawner.rs` + +### Pravilnik načina priv — `enforce_statfs=1`, brez `allow.mount` + +Vse ječe delijo privzeti pravilnik, ki prepoveduje priklope, surova vtičnice, +spreminjanje lastništva in dostop do naprav. Vsaka priklopna točka, ki jo +agent potrebuje (repozitoriji, vtičnica demona, imeniki stanja), je izrecno +navedena v konfiguraciji Bastille. + +### Ista omejitev zaganjalnika za MCP kot za agente + +Ko se zažene strežnik MCP, uporabi isti mehanizem spawnanja v ječi kot +agenti. Predloga ječe (`clawdie-mcp`), konfiguracija Bastille, pravilnik +načina priv in uporabnik so enaki. Edina razlika: ječa ni trajna. + +→ `crates/colibri-mcp/src/lib.rs` + +## Glej tudi + +- [deployment](./deployment.md) — postavitev ZFS za ječe +- [vault-provision](./vault-provision.md) — oskrba okolja znotraj ječ diff --git a/docs/wiki/sl/runtime-inventory.md b/docs/wiki/sl/runtime-inventory.md new file mode 100644 index 0000000..825dfeb --- /dev/null +++ b/docs/wiki/sl/runtime-inventory.md @@ -0,0 +1,48 @@ +--- +title: Popis izvajalnega okolja +description: Bralnik stanja gostitelja — aditivne, bralne integracije, ki zbirajo različice OS, paketov in izvajalnega okolja. +--- + +← [kazalo](./index.md) + +Bralnik popisa izvajalnega okolja je aditivna, bralna plast: bere dejstva o +gostitelju, ne da bi karkoli spremenil. Je vhod za razporejevalnik (ali lahko +ta gostitelj izvede opravilo?) in za matični register (kaj ta gostitelj je?). + +→ `crates/colibri-runtime-inventory/src/lib.rs` + +## Odločitve + +### Aditivno, ne konfiguracijsko + +Bralnik odkrije dejstva, ne uveljavlja stanja. Če manjka `pi` ali `zot`, to +zabeleži — ne namesti. Če je prisotnih več različic Node.js, jih navede vse. +Če je ZFS odklopljen, to zabeleži — ne uvozi bazena. Operater se odloči, kaj +storiti s popisom. + +### Bralni vmesnik, specifičen za platformo + +`HostInfo` je skupen struct. Vsaka platforma implementira `HostReader` trait. +FreeBSD-jev bralnik uporablja `pkg`, `sysctl`, `zfs`, `kldstat` in `pciconf`. +Linuxov bralnik uporablja `uname`, `/proc`, `lsblk` in `lspci`. Skupna +struktura pomeni, da razporejevalnik in mati vidita isto obliko ne glede na +OS. + +→ `crates/colibri-runtime-inventory/src/platform.rs` + +### Rezultat je JSON, konzumirajo ga trije porabniki + +Popis se serializira v `clawdie.runtime-version-inventory.v1`. Trije porabniki: + +- **Razporejevalnik**: ujemanje zmožnosti (`"can_run_local_llm": true`). +- **Mati**: register hive (`"hostname": "domedog"`, `"os": "linux"`). +- **Operater**: ukaz `colibri runtime-inventory`. + +### Brez pisanja — integracije so samo za branje + +Bralnik ne piše v podatkovno zbirko, ne spreminja konfiguracije in ne +spreminja stanja demona. Je čista funkcija `HostReader::read() → HostInfo`. +To pomeni, da je varno zagnati ga v cronu, ob zagonu ali ročno brez stranskih +učinkov. + +→ [contracts](./contracts.md) (shema) | [mother-hive](./mother-hive.md) diff --git a/docs/wiki/sl/skills-catalog.md b/docs/wiki/sl/skills-catalog.md new file mode 100644 index 0000000..151c5b3 --- /dev/null +++ b/docs/wiki/sl/skills-catalog.md @@ -0,0 +1,45 @@ +--- +title: Katalog veščin +description: Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI — uvozi SKILL.md v Colibrijevo tabelo skills. +--- + +← [kazalo](./index.md) + +Katalog veščin je Colibrijev bralni izvajalni porabnik za veščine, +pregledane v repozitoriju `clawdie-ai`. Veščine se uvozijo v tabelo +`skills` v shrambi SQLite, kjer jih agenti poizvedujejo med izvajanjem. + +→ `scripts/import-clawdie-skills.sh` + +## Odločitve + +### Bralni porabnik, ne vir resnice + +Colibri bere veščine iz repozitorija `clawdie-ai` — ta je vir. Uvozna +skripta je idempotentna (`INSERT OR IGNORE`), zato je varno večkrat +zagnati. Spremembe veščin se zgodijo v izvornem repozitoriju, nato se +ponovno uvozijo. + +→ [layered-soul](./layered-soul.md) (enaka smer) + +### Ena tabela, ploščata + +Vse veščine si delijo eno tabelo `skills` s stolpci `name`, `description`, +`category` in `created_at`. Kategorija je prosta besedilna oznaka +(`"soul"`, `"agent"`, `"channel"`). Brez gnezdenja, brez različic, brez +odvisnosti med veščinami. To ustreza trenutnemu obsegu (~50 veščin). + +→ `crates/colibri-store/src/schema.rs` + +### Uvoz ob zagonu, ne sproti + +Veščine se uvozijo ob zagonu demona, ne med izvajanjem. Če operater doda +veščino, ponovno zažene demona (ali ročno zažene uvozno skripto). Nobena pot +izvajalne kode ne piše v tabelo `skills`. + +→ `scripts/import-clawdie-skills.sh` + +## Glej tudi + +- [layered-soul](./layered-soul.md) — veščine iz layered-soul +- [store-schema](./store-schema.md) — shema tabele skills diff --git a/docs/wiki/sl/vault-provision.md b/docs/wiki/sl/vault-provision.md new file mode 100644 index 0000000..51429b7 --- /dev/null +++ b/docs/wiki/sl/vault-provision.md @@ -0,0 +1,49 @@ +--- +title: Oskrba trezorja +description: Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta — preslikava najemnik → ječa → zbirka. +--- + +← [kazalo](./index.md) + +`colibri-vault` bere skrivnosti iz Vaultwarden in jih zapiše kot datoteke +okolja (`.env`) znotraj ječ, preden se agent zažene. Vsak najemnik dobi +svojo datoteko `.env` s točno tistimi poverilnicami, ki jih potrebuje — +nič več. + +→ `crates/colibri-vault/src/lib.rs` + +## Odločitve + +### 1:1:1 preslikava — najemnik = ječa = zbirka + +Preslikava `tenant_id → ime ječe → zbirka Vaultwarden` je nespremenljiva. +Ukaz `colibri vault-provision ` poišče vrstico najemnika v SQLite, +pridobi vse skrivnosti iz imenovane zbirke Vaultwarden in jih zapiše v +`/tmp/.env` znotraj ječe. + +### CLI Vaultwarden (`bw`), ne API + +Oskrbnik uporablja `bw` (uradni CLI Vaultwarden/Bitwarden). seja `bw` se +odpre s ključem API, ki je shranjen kot skrivnost v `bw_session`, in zapre +po vsakem zagonu oskrbe. Brez trajnih sej, brez predpomnjenih žetonov. + +→ `crates/colibri-vault/src/vaultwarden.rs` + +### Skrivnosti so začasne znotraj ječe + +Datoteka `.env` je zapisana v `/tmp/.env` — obstojna samo toliko časa, +kolikor živi ječa. Če je ječa uničena in ponovno ustvarjena, oskrbnik +znova zažene. Skrivnosti niso nikoli shranjene na gostitelju. + +### Oskrba ob zagonu agenta, ne periodično + +Oskrba teče enkrat, tik preden se agent zažene znotraj ječe. Brez cron +osveževanj, brez rotacije skrivnosti med izvajanjem. Če se skrivnost spremeni, +operater ustavi in znova zažene agenta. + +→ `crates/colibri-daemon/src/socket.rs` (`cmd_spawn_agent`) + +## Glej tudi + +- [store-schema](./store-schema.md) — preslikava `tenants` +- [jail-confinement](./jail-confinement.md) — kako so ječe ustvarjene -- 2.45.3 From c38b5f1e5bcd0ebc61c45b13c0253d4feaae751a Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:13:12 +0200 Subject: [PATCH 06/19] docs(guide): trim install Scope paragraph to one-liner Match the lean SL style: one terse sentence, no legacy narration. "clawdie provisions the host service. Jail, DB, CMS, and Git provisioning are not yet in the installer." --- docs/guide/install/install.md | 247 +++++++--------------------------- 1 file changed, 50 insertions(+), 197 deletions(-) diff --git a/docs/guide/install/install.md b/docs/guide/install/install.md index b528646..44aee3e 100644 --- a/docs/guide/install/install.md +++ b/docs/guide/install/install.md @@ -1,232 +1,85 @@ --- -title: Install Orchestrator -description: Single-command install flow for Clawdie. +title: Install +description: Provision the Clawdie host service with the clawdie binary. --- -**Command:** `just install` +**Command:** `clawdie apply --yes` -## Quick start +Colibri-based Clawdie is installed by the **`clawdie`** binary (crate +`crates/clawdie`). It discovers the host's ZFS layout and provisions the +`clawdie` service: storage datasets, a service user, and the rc.d (FreeBSD) or +systemd (Linux) unit that runs `colibri-daemon`. -Clawdie tracks the FreeBSD 15.x line. The installer rejects FreeBSD 14.x and any unvalidated future major version. +This repo is a **Cargo workspace** — there is no `just`/npm install flow here. +Build the installer from the workspace: ```bash -just install +cargo build -p clawdie --release ``` -## ISO path - -Current ISO validation is converging on: live QML installer → first installed -boot → loopback-bound controlplane `/setup` with a one-time bootstrap token. -Provider keys and Telegram are configured there after install. The older -[`setup.txt` first-boot contract](./first-boot/) remains documented for legacy -non-interactive work and will be rewritten after live ISO validation. - -After the initial boot, the same `install` flow described here runs in the -background. - -Resume from a specific step after a failure: +## Commands ```bash -just install-from-db +clawdie discover # read-only: OS, ZFS pools, datasets, spare disks +clawdie plan [--pool NAME] # show the deploy plan (dry-run, no writes) +clawdie apply [--pool NAME] # dry-run unless --yes is given +clawdie apply --yes # provision: storage layout + install the service ``` -Skip service jails (db, git, cms) when running `DB_RUNTIME=host` or installing a second agent on an existing host: +`apply` is a **dry-run by default** and prints the full step plan; it writes to +disk only with `--yes`. When the host has exactly one ZFS pool it is selected +automatically; with several, pass `--pool NAME`. -```bash -just install-from hosts -``` +## Storage strategy -Print the step plan without running anything: +| Host | Behavior | +| ------------------ | ---------------------------------------------------------------------------------------------------------- | +| FreeBSD | ZFS is **required**; datasets are created under the chosen pool. | +| Linux + ZFS + pool | Same — datasets under the pool. | +| Linux, no ZFS/pool | Falls back to plain directories, and reports the ZFS benefits plus any spare disks that could host a pool. | -```bash -just install -- --dry-run -``` - -Skip ZFS checkpoints (e.g. no ZFS pool): - -```bash -just install -- --no-snapshots -``` - ---- - -## Step flow - -``` -just install - │ - ▼ - ┌─────────────────────────────────────────────────────────┐ - │ Detect ZFS dataset (zroot/bastille) │ - │ Parse --from / --no-snapshots / --dry-run │ - └─────────────────────────────────────────────────────────┘ - │ - ▼ -[ 1] onboarding first-boot setup seed or TUI fallback REQUIRED - │ -[ 2] environment host pkg baseline, bridge, locale REQUIRED - │ -[ 3] agent-config validate/write agent provider optional ─── warn on missing provider auth - │ └── pi missing → warn, continue -[ 4] pf write PF include (NAT egress) REQUIRED - │ └── 📸 snapshot: post-pf -[ 5] jails create worker jail (--create) REQUIRED - │ └── 📸 snapshot: post-jails -[ 6] git Git Service (git jail) DEFAULT ─── DB_RUNTIME=host → skip or use install-from hosts - │ └── 📸 snapshot: post-git -[ 7] forgejo Forgejo for Git Service DEFAULT ─── FEATURE_GITEA=NO → skip - │ -[ 8] db Data Service (PostgreSQL) DEFAULT ─── DB_RUNTIME=host → skip; DB on host instead - │ └── 📸 snapshot: post-db -[ 9] skills-memory built-in knowledge import DEFAULT ─── artifact.sql ships in tarball - │ -[10] skills-init Skills engine init (.nanoclaw) DEFAULT - │ -[11] cms Web Service (cms jail: Astro+nginx) DEFAULT ─── use install-from hosts to skip - │ └── 📸 snapshot: post-cms - │ -[12] ollama Local AI Models (Ollama jail .5) optional ─── FEATURE_OLLAMA≠YES → skip - │ -[13] llama-cpp Local AI Models (llama-cpp jail .5) optional ─── FEATURE_LLAMA_CPP≠YES → skip - │ -[14] hosts /etc/hosts + jail hostnames REQUIRED - │ -[15] mounts validate jail mounts REQUIRED - │ -[16] telegram-auth verify bot token optional ─── TELEGRAM_BOT_TOKEN unset → skip - │ -[17] service build + install rc.d service REQUIRED - │ -[18] hostd privileged host daemon (hostd) REQUIRED - │ -[19] identity-restore Supabase restore optional ─── SUPABASE_URL unset → skip - │ -[20] verify integrity check optional - │ └── 📸 snapshot: install-complete - │ - ▼ - ┌─────────────────────────────────────────────────────────┐ - │ Summary: N ok N warnings N skipped N failed │ - │ Snapshots taken: zroot/bastille@post-pf-… … │ - │ LLM providers: anthropic ✓ openai ✗ ollama ✗ … │ - └─────────────────────────────────────────────────────────┘ -``` - -The onboarding step prefers the first-boot setup file (`setup.txt`; see -[First boot](./first-boot/)). The interactive TUI wizard is the fallback when -the first-boot setup is absent or invalid; it sources locales from FreeBSD -itself, so any installed locale can be selected (`en_US.UTF-8`, -`zh_CN.UTF-8`, etc.) and is applied consistently. -`setup.txt` is the operator-intent contract, and `system.env` is the matching -hardware-intent contract. Inspect can populate both before the installer runs. -Set `DB_RUNTIME=host` in `.env` to provision PostgreSQL directly on the host instead of a db jail; `DB_HOST` defaults to `${AGENT_SUBNET_BASE}.1` so jails can reach it. Use `DB_COMPRESSION=lz4` (default) or `DB_COMPRESSION=zstd` for ZFS compression on host datasets. - -The root install owns shared platform services. It is not modeled as tenant zero. -`ASSISTANT_NAME` is display-only. Later additive tenants consume shared services such as: - -- Git Service -- Web Service -- Local AI Models - ---- - -## ZFS snapshots - -Snapshots are taken after each milestone step if a Bastille ZFS dataset is -detected. Two paths: - -| Context | Method | -| ------------------------------ | ------------------------------------------------------------- | -| Running as root | `zfs snapshot zroot/bastille@` directly | -| Non-root, `sudo` available | `sudo zfs snapshot zroot/bastille@` | -| Non-root, hostd socket present | `nc -U /var/run/-hostd.sock` (hostd `zfs-snapshot` op) | -| Neither | skip silently | - -Snapshot tags are suffixed with a Unix timestamp to prevent collisions on re-runs. - ---- - -## LLM providers - -The orchestrator never exits on missing LLM provider auth. OpenAI/OpenRouter/Anthropic -subscription auth is the recommended path for performance/price, but it is not a -hard installer requirement and all supported providers are peer options. At the -end of the run Clawdie prints a table of known providers: - -``` -△ LLM providers - anthropic ANTHROPIC_API_KEY ✓ configured - openai OPENAI_API_KEY ✗ not set - openrouter OPENROUTER_API_KEY ✗ not set - deepseek DEEPSEEK_API_KEY ✗ not set - zai ZAI_API_KEY ✗ not set - groq GROQ_API_KEY ✗ not set - azure AZURE_OPENAI_API_KEY ✗ not set - ollama OLLAMA_HOST ✗ not set -``` - -If no provider auth is found, it prints instructions: - -``` - No LLM provider auth found. Configure one after install and restart: - Set DEEPSEEK_API_KEY=... in provider.env for the default agent, - or add provider keys such as ANTHROPIC_API_KEY=sk-ant-... - service clawdie restart -``` - -The entire infrastructure (PF, jails, PostgreSQL, nginx, ZFS) has zero -LLM dependency. Provider auth is only consumed when the jail-runner spawns a -live response. Install and service start succeed without it. - -After install, use the controlplane setup page to finish provider and optional -Telegram configuration: +ZFS layout under the pool: ```text -https:///setup +/clawdie (container, canmount=off) +/clawdie/db -> /var/db/clawdie +/clawdie/log -> /var/log/clawdie ``` -Before setup is complete, do not expose this URL directly to the public internet. -Use local console/loopback access, or a tailnet/LAN path protected by TLS and -network allowlisting. The bootstrap token is a first-setup key, not a substitute -for bind/PF/TLS policy. +## What `apply --yes` provisions -If the printed bootstrap token is lost before setup completes, rotate a fresh -one on the host: +1. **Storage** — the datasets above (or plain `/var/db/clawdie` + + `/var/log/clawdie` on the plain-dirs fallback). +2. **Service user** — `clawdie` (nologin), owning the state directories + (`clawdie:clawdie`). +3. **Service** — the rc.d script (FreeBSD, via `daemon -u clawdie`) or systemd + unit (Linux, `User=clawdie`), installed and enabled to run + `/usr/local/bin/colibri-daemon`. -```sh -npm run setup-token -- rotate -``` +## Creating a pool (destructive) -### Agent runtime setup - -The agent runtime uses `DEEPSEEK_API_KEY` from `provider.env`. -Colibri autospawns zot in RPC mode — no separate login or auth store -needed. zot reads its identity from `$ZOT_HOME/AGENTS.md` (installed -automatically from the seed partition). - -Quick verification: +On a host with a spare disk and no usable pool: ```bash -zot --no-session --print "Reply with exactly: zot-ok" +clawdie apply --pool NAME --create-pool /dev/DEV --yes ``` -Expected output: +`--create-pool` runs `zpool create` on `DEV` and **destroys all data on it**, so +it is refused unless the disk is detected as empty (no partitions/filesystem/ +mount, not the root disk). Override that guard with `--force` only if you are +certain. -```text -zot-ok -``` +## Safety -### Control plane API auth +Disk-touching steps (`zfs`/`zpool create`, service install) run as root on the +target host. `discover`, `plan`, and a bare `apply` never write — preview with +`plan` first. -Agent subprocesses (pi, aider) authenticate back to the control plane -API using a shared secret. Generate one after install: +## Scope -```bash -echo "CONTROLPLANE_SHARED_SECRET=$(openssl rand -base64 32)" >> .env -sudo service ${AGENT_NAME} restart -``` +`clawdie` provisions the host service. Jail, DB, CMS, and Git provisioning are not yet in the installer. -Without it, the startup log warns and agent-to-API calls are rejected. +## FreeBSD validation ### Service wrapper scripts -- 2.45.3 From 3145a725c619f9b15fc713da14f5d9fe7ac35efc Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:19:00 +0200 Subject: [PATCH 07/19] docs(sl): add 23 Slovenian terminology mappings to glossary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New Izrazoslovje section — English concept → Slovenian name mapping: jail/ječa, warden/paznik, confinement/zaprtost, prisoner/zapornik, cell/celica, hive/panj, mother/matično vozlišče, node/vozlišče, glasspane/steklena plošča, spawn/(samodejni) zagon, seed/seme, vault/trezor, tenant/najemnik, skill/veščina, snapshot/posnetek, rollback/povratek, harvest/žetev, bridge/most, daemon/ozadnji proces, board/tabla nalog, scheduler/razporejevalnik, Bastille (trdnjava), jailed/zaprt v ječi. Cross-links added from existing ZFS, PF, and UI entries. Total anchors: 38 (15 abbreviations + 23 terminology). --- docs/guide/sl/reference/okrajsave.md | 148 ++++++++++++++++++++++++++- 1 file changed, 145 insertions(+), 3 deletions(-) diff --git a/docs/guide/sl/reference/okrajsave.md b/docs/guide/sl/reference/okrajsave.md index b0424e2..6afe7aa 100644 --- a/docs/guide/sl/reference/okrajsave.md +++ b/docs/guide/sl/reference/okrajsave.md @@ -50,7 +50,7 @@ LLM za vse agentske odločitve. ## NAT **Network Address Translation** — prevajanje omrežnih naslovov; omogoča, da več -naprav deli en javni IP. PF na FreeBSD samodejno nastavi NAT za ječe. +naprav deli en javni IP. PF na FreeBSD samodejno nastavi NAT za [ječe](#jail). ## PF @@ -72,7 +72,8 @@ vratih TCP. ## UI **User Interface** — uporabniški vmesnik, kar operater vidi na zaslonu. -Glasspane TUI je terminalski vmesnik za nadzor agentov. +Glasspane TUI je terminalski vmesnik za nadzor agentov. Glej tudi: +[glasspane](#glasspane). ## VPS @@ -84,4 +85,145 @@ VPS. **Zettabyte File System** — napredni datotečni sistem, ki ga uporablja FreeBSD. Omogoča posnetke (snapshots), stiskanje in preverjanje celovitosti -podatkov. Clawdie zahteva ZFS za ječe Bastille. +podatkov. Clawdie zahteva ZFS za [ječe](#jail) Bastille. Glej tudi: + +## Izrazoslovje — angleško-slovenski preslikovalnik + +Tehnično izrazoslovje v kodi ostaja v angleščini (ukazi, poti, imena +spremenljivk). Slovenski prevodi so mišljeni za **branje in razumevanje** +dokumentacije, ne za pisanje kode. + +### Bastille + +Orodje za upravljanje ječ na FreeBSD. Ime izhaja iz trdnjave Bastilja. + +### board (task board) + +**Tabla nalog** — seznam nalog, ki čakajo na dodelitev agentom. Vsaka naloga +ima zahtevane zmožnosti (capabilities) in jih razporejevalnik (scheduler) +dodeli najprimernejšemu agentu. + +### bridge + +**Most** — omrežni most, ki povezuje ječe z zunanjim svetom. `warden0` je +most, ki ga Bastille uporablja za omrežje ječ. + +### cell + +**Celica** — posamezna enota znotraj ječe. Tanke (thin) celice si delijo +predlogo, debele (thick) so samostojne. + +### confinement + +**Zaprtost** — stopnja izolacije procesa. Ječa (jail) je najmočnejša oblika +zaprtosti na FreeBSD: proces ne vidi gostitelja, nima dostopa do omrežja +(glede na nastavitve) in ne more pobegniti. + +### daemon + +**Ozadnji proces** — program, ki teče v ozadju, brez neposrednega upravljanja. +Na FreeBSD jih upravlja `rc.d`. `colibri-daemon` je ozadnji proces, ki +nadzoruje agente. + +### glasspane + +**Steklena plošča / nadzorna plošča** — Colibrijeva opazovalna plast. +Spremlja agente prek JSONL in jih preslika v pet stanj: Idle → Working → +Blocked → Done / Error. + +### harvest + +**Žetev** — zajem podatkov o strojni opremi (`clawdie-hw-probe`). +Pobrano (harvested) se pošlje matičnemu vozlišču (mother) prek MCP. + +### hive + +**Panj** — vsa vozlišča, povezana z matičnim vozliščem. `hive_nodes` je +tabela v PostgreSQL na matičnem vozlišču, ki beleži vsako vozlišče, njegovo +strojno opremo in zmožnosti. + +### jail + +**Ječa** — varnostni mehanizem FreeBSD za izolacijo procesov. Proces v ječi +vidi le svoj datotečni sistem in omejeno omrežje. Clawdie uporablja ječe +Bastille za izolacijo agentov in zunanjih MCP strežnikov. Glej tudi: +[confinement](#confinement), [warden](#warden), [prisoner](#prisoner). + +### jailed + +**Zaprt v ječi** — stanje procesa, ki teče znotraj ječe. Proces, ki je +*zaprt v ječi*, nima dostopa do gostitelja. Nasprotje je *na prostosti* +(teče na gostitelju brez izolacije). + +### mother (mother node) + +**Matično vozlišče** — osrednji strežnik, ki vodi register vseh vozlišč +(`hive_nodes`). USB-vozlišča se mu javijo prek MCP prek SSH. Matično vozlišče +hrani PostgreSQL in dodeljuje naloge. + +### node + +**Vozlišče** — katerikoli gostitelj, ki je del panja: USB-ključek, nameščen +disk, VPS ali matično vozlišče samo. Vsako vozlišče ima `node_type` in +se registrira prek `node_register`. + +### prisoner (prisoner process) + +**Zapornik / zaprt proces** — proces, ki teče v ječi. Nima dostopa do +gostiteljevega datotečnega sistema in omrežja (razen če mu je izrecno +dovoljeno). + +### rollback + +**Povratek** — vrnitev na prejšnje stanje. ZFS snapshots omogočajo povratek +celotnega datotečnega sistema. `bectl activate` omogoča povratek na prejšnji +zagonski posnetek. + +### scheduler + +**Razporejevalnik** — del krmilne ravnine, ki vsakih ~30s preveri, katere +naloge so na vrsti, in jih dodeli najprimernejšemu prostemu agentu. + +### seed (CLAWDIESEED) + +**Seme / semenski del** — tretja rezina (slice) na USB-ključku, formatirana +kot FAT32. Vsebuje skrivnosti (ključe, API žetone, gesla), ki jih uvoznik +(`clawdie-live-seed`) ob zagonu namesti. Seme je **ločeno od slike ISO** — +operater ga ureja po zapisu slike, pred zagonom. + +### skill + +**Veščina** — paket zmožnosti, ki ga agent lahko naloži, da opravi določeno +nalogo. Primer: `jail-status` (preveri stanje ječ), `db-vacuum` (počisti +bazo). Veščine so v katalogu in jih uvaža `import-colibri-skills.sh`. + +### snapshot + +**Posnetek** — trenutno stanje datotečnega sistema, shranjeno kot ZFS +snapshot. Posnetki so osnova za povratek (rollback) in jih samodejno +upravlja `sanoid`. + +### spawn (autospawn) + +**(Samodejni) zagon agenta** — krmilna ravnina ob zagonu požene agenta +(`zot`), če je omogočeno `COLIBRI_AUTOSPAWN=YES`. Agent dobi RPC poziv +in začne z delom. + +### tenant + +**Najemnik** — večnajemniška enota. Vsak najemnik ima svoje okolje, +skrivnosti in naloge. Krmilna ravnina podpira več najemnikov na enem +vozlišču. + +### vault + +**Trezor / sef** — varno hranjenje skrivnosti (gesla, API ključi, žetoni). +Clawdie uporablja Vaultwarden (Bitwarden API) za upravljanje skrivnosti +najemnikov. + +### warden + +**Paznik** — upravljalec ječ. Na FreeBSD je to `jail(8)` ali `warden0` +(omrežni most ječ Bastille). Na matičnem vozlišču je to `colibri-mcp-ssh`, +ki nadzoruje, kateri ukazi so dovoljeni čez SSH. *Paznik* je slovenski izraz +za paznika v zaporu — čuva ječo in njene zapornike. -- 2.45.3 From f704abc78268d1f7c7ee72ca4f9a05f0d9c1687a Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:31:23 +0200 Subject: [PATCH 08/19] feat(wiki): minimal Astro site for wiki.clawdie.si MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plain Astro — no Starlight. Five files: - package.json (astro only, v0.12.0) - astro.config.mjs (wiki.clawdie.si, static output) - src/pages/index.astro (flat list of all decision pages) - src/pages/[...slug].astro (dynamic route: reads docs/wiki/*.md) - build-wiki.sh (npm ci + astro build) Design decisions: - No Starlight — 23 pages, rarely changing, primary audience is LLMs - Dynamic routes — add a .md to docs/wiki/, it automatically gets a page - Markdown rendered at build time (frontmatter, tables, code blocks, links) - Wiki links [label](./page.md) auto-resolve to [/page/] - Dark mode via prefers-color-scheme, no JS Guide keeps Starlight (structured sidebar, human operators). Wiki gets plain Astro (flat list, agent audience). See: docs/PLAN-WIKI-CLAWDIE-SI.md --- astro/wiki/.gitignore | 3 + astro/wiki/astro.config.mjs | 12 +++ astro/wiki/package.json | 14 +++ astro/wiki/src/pages/[...slug].astro | 131 +++++++++++++++++++++++++++ astro/wiki/src/pages/index.astro | 60 ++++++++++++ docs/PLAN-WIKI-CLAWDIE-SI.md | 49 ++++++++++ scripts/build-wiki.sh | 29 ++++++ 7 files changed, 298 insertions(+) create mode 100644 astro/wiki/.gitignore create mode 100644 astro/wiki/astro.config.mjs create mode 100644 astro/wiki/package.json create mode 100644 astro/wiki/src/pages/[...slug].astro create mode 100644 astro/wiki/src/pages/index.astro create mode 100644 docs/PLAN-WIKI-CLAWDIE-SI.md create mode 100755 scripts/build-wiki.sh diff --git a/astro/wiki/.gitignore b/astro/wiki/.gitignore new file mode 100644 index 0000000..ddce69b --- /dev/null +++ b/astro/wiki/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +dist/ +.astro/ diff --git a/astro/wiki/astro.config.mjs b/astro/wiki/astro.config.mjs new file mode 100644 index 0000000..3e3a004 --- /dev/null +++ b/astro/wiki/astro.config.mjs @@ -0,0 +1,12 @@ +import { defineConfig } from "astro/config"; + +const site = process.env.ASTRO_SITE_URL || "https://wiki.clawdie.si"; +const outDir = process.env.ASTRO_OUT_DIR || "./dist"; + +// https://astro.build/config +export default defineConfig({ + site, + outDir, + output: "static", + trailingSlash: "always", +}); diff --git a/astro/wiki/package.json b/astro/wiki/package.json new file mode 100644 index 0000000..8c29066 --- /dev/null +++ b/astro/wiki/package.json @@ -0,0 +1,14 @@ +{ + "name": "clawdie-wiki", + "private": true, + "version": "0.12.0", + "type": "module", + "scripts": { + "dev": "astro dev --host 0.0.0.0", + "build": "astro build", + "preview": "astro preview --host 0.0.0.0" + }, + "dependencies": { + "astro": "^5.16.11" + } +} diff --git a/astro/wiki/src/pages/[...slug].astro b/astro/wiki/src/pages/[...slug].astro new file mode 100644 index 0000000..d27194c --- /dev/null +++ b/astro/wiki/src/pages/[...slug].astro @@ -0,0 +1,131 @@ +--- +import fs from "node:fs"; +import path from "node:path"; + +const WIKI_DIR = path.resolve("../../docs/wiki"); +const EXCLUDE = [".git", "sl", "index.md"]; + +export function getStaticPaths() { + function walk(dir, prefix = "") { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const slugs = []; + for (const e of entries) { + if (e.name.startsWith(".") || EXCLUDE.includes(e.name)) continue; + const full = path.join(dir, e.name); + if (e.isDirectory()) { + slugs.push(...walk(full, prefix ? `${prefix}/${e.name}` : e.name)); + } else if (e.name.endsWith(".md")) { + const rel = prefix ? `${prefix}/${e.name}` : e.name; + slugs.push({ params: { slug: rel.replace(/\.md$/, "") } }); + } + } + return slugs; + } + return walk(WIKI_DIR); +} + +const { slug } = Astro.params; +const filePath = path.join(WIKI_DIR, `${slug}.md`); + +if (!fs.existsSync(filePath)) { + return new Response("Not found", { status: 404 }); +} + +const raw = fs.readFileSync(filePath, "utf-8"); + +// Parse frontmatter +let content = raw; +let frontmatter = {}; +if (raw.startsWith("---")) { + const end = raw.indexOf("---", 3); + if (end !== -1) { + const fm = raw.slice(3, end); + for (const line of fm.split("\n")) { + const m = line.match(/^(\w+):\s*(.+)$/); + if (m) frontmatter[m[1]] = m[2].replace(/^["']|["']$/g, ""); + } + content = raw.slice(end + 3).trim(); + } +} + +// Resolve relative wiki links [label](./page.md) → [label](/page/) +const resolveLinks = (md) => + md.replace(/\]\(\.\/([^)]+)\.md\)/g, "](/$1/)") + .replace(/\]\(\.\.\/([^)]+)\.md\)/g, "](/$1/)"); + +content = resolveLinks(content); + +// Render fenced code blocks +const renderCode = (md) => + md.replace(/```(\w*)\n([\s\S]*?)```/g, (_, lang, code) => { + return `
${code.trim()}
`; + }); + +content = renderCode(content); + +// Render tables +const renderTables = (md) => { + return md.replace(/\|(.+)\|\n\|[-| ]+\|\n((?:\|.+\|\n?)*)/gm, (_, header, rows) => { + const hcells = header.split("|").map(c => c.trim()).filter(Boolean); + const thead = `${hcells.map(c => `${c}`).join("")}`; + const tbody = rows.trim().split("\n").map(row => { + const cells = row.split("|").map(c => c.trim()).filter(Boolean); + return `${cells.map(c => `${c}`).join("")}`; + }).join(""); + return `${thead}${tbody}
`; + }); +}; +content = renderTables(content); + +// Render inline code, bold, italic, links, headings, lists +content = content + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\*([^*]+)\*/g, "$1") + .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1') + .replace(/^### (.+)$/gm, "

$1

") + .replace(/^## (.+)$/gm, "

$1

") + .replace(/^# (.+)$/gm, "

$1

") + .replace(/^- (.+)$/gm, "
  • $1
    • ") + .replace(/((?:
  • .*<\/li>\n?)+)/g, "
      $1
    ") + .replace(/\n\n/g, "

    ") + .replace(/^(.+)$/gm, (line) => { + if (line.startsWith("<")) return line; + return line; + }); + +const title = frontmatter.title || slug; +--- + + + + + + {(title)} — Colibri Wiki + + + +

    +
    +

    {title}

    +

    +

    + + diff --git a/astro/wiki/src/pages/index.astro b/astro/wiki/src/pages/index.astro new file mode 100644 index 0000000..5e628c2 --- /dev/null +++ b/astro/wiki/src/pages/index.astro @@ -0,0 +1,60 @@ +--- +import fs from "node:fs"; +import path from "node:path"; + +const WIKI_DIR = path.resolve("../../docs/wiki"); +const EXCLUDE = [".git", "sl", "index.md"]; + +function walkMarkdown(dir, prefix = "") { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const files = []; + for (const e of entries) { + if (e.name.startsWith(".") || EXCLUDE.includes(e.name)) continue; + const full = path.join(dir, e.name); + if (e.isDirectory()) { + files.push(...walkMarkdown(full, prefix ? `${prefix}/${e.name}` : e.name)); + } else if (e.name.endsWith(".md")) { + const rel = prefix ? `${prefix}/${e.name}` : e.name; + const slug = rel.replace(/\.md$/, ""); + // Skip frontmatter, grab first H1 as title + const raw = fs.readFileSync(full, "utf-8"); + const title = raw.match(/^#\s+(.+)$/m)?.[1] || slug; + files.push({ slug, title, file: rel }); + } + } + return files.sort((a, b) => a.title.localeCompare(b.title)); +} + +const pages = walkMarkdown(WIKI_DIR); +--- + + + + + + Colibri Wiki + + + +

    Colibri Wiki

    +

    + Decision pages — the why behind the architecture. + LLM Wiki pattern. +

    + + + diff --git a/docs/PLAN-WIKI-CLAWDIE-SI.md b/docs/PLAN-WIKI-CLAWDIE-SI.md new file mode 100644 index 0000000..69561d2 --- /dev/null +++ b/docs/PLAN-WIKI-CLAWDIE-SI.md @@ -0,0 +1,49 @@ +# wiki.clawdie.si — separate domain for decision pages + +**Status:** planned · **Created:** 26.jun.2026 · **Blocks:** nothing in 0.12 + +## Goal + +Split the current docs.clawdie.si (single site) into two domains during the +Astro migration from clawdie-ai → colibri: + +``` +docs.clawdie.si → guide (procedural: install, operate, reference) +wiki.clawdie.si → wiki (decisions: architecture rationale, LLM-wiki) +clawdie.si → landing (unchanged) +``` + +## Why + +- Wiki stays pure Karpathy LLM-wiki pattern — one decision per page, flat list +- Guide stays procedural — structured sidebar with install/operate/architecture +- Different audiences: wiki for agents/architects, guide for operators +- ISO can toggle each surface independently (FEATURE_DOCS, FEATURE_WIKI) + +## What needs building + +| Layer | Task | +|---|---| +| DNS | `wiki.clawdie.si` A/AAAA → same host | +| TLS | New Let's Encrypt cert (acme.sh auto-renew) | +| Nginx | New vhost for wiki.clawdie.si | +| Astro | Two Starlight configs from one colibri source tree | +| Build | `build-docs.sh` → dist-guide/ + dist-wiki/ | +| ISO | `FEATURE_DOCS` / `FEATURE_WIKI` toggle knobs | + +## Two Starlight configs + +``` +colibri/astro/ + guide.config.mjs → full sidebar: Install, Operate, Architecture... + wiki.config.mjs → minimal sidebar: autogenerate flat article list +``` + +Same toolchain, two configs, two output dirs. Wiki uses autogenerate — no +manual sidebar to maintain as pages are added. + +## Prerequisite + +The Astro build pipeline must be migrated from clawdie-ai to colibri first. +The content already lives in colibri (docs/guide/ + docs/wiki/). The build +scripts and Astro config don't yet. diff --git a/scripts/build-wiki.sh b/scripts/build-wiki.sh new file mode 100755 index 0000000..e91d189 --- /dev/null +++ b/scripts/build-wiki.sh @@ -0,0 +1,29 @@ +#!/bin/sh +# Build the Colibri wiki site — plain Astro, no Starlight. +# +# Prerequisites: Node.js + npm (node24 npm-node24 on FreeBSD). +# cd astro/wiki && npm ci +# +# Usage: +# ./scripts/build-wiki.sh # build to astro/wiki/dist/ +# ./scripts/build-wiki.sh --preview # dev server at localhost:4321 +# +# Site URL override: +# ASTRO_SITE_URL=https://wiki.clawdie.si ./scripts/build-wiki.sh + +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +REPO_ROOT=$(cd "$SCRIPT_DIR/.." && pwd) +WIKI_DIR="$REPO_ROOT/astro/wiki" + +cd "$WIKI_DIR" + +if [ "${1:-}" = "--preview" ]; then + echo "==> wiki dev server (http://localhost:4321)" + npx astro dev --host 0.0.0.0 +else + echo "==> building wiki ($WIKI_DIR)" + npx astro build + echo "==> wiki built → $WIKI_DIR/dist/" +fi -- 2.45.3 From cbf707be8f584557325961fbfe27d730f4778b23 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 11:51:02 +0200 Subject: [PATCH 09/19] feat(wiki): add Slovenian locale support with unified path pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove 'sl' from EXCLUDE — Slovenian wiki pages now served - Locale-aware link resolver: ./page.md → /sl/page/ in sl/ context - Language switcher in nav bar (English ↔ Slovenščina) - Slovenian index at /sl/ with translated prose - lang attribute dynamic per locale - Matches docs.clawdie.si Starlight pattern: /// --- astro/wiki/src/pages/[...slug].astro | 33 +++++++++++--- astro/wiki/src/pages/index.astro | 17 +++++--- astro/wiki/src/pages/sl/index.astro | 64 ++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 13 deletions(-) create mode 100644 astro/wiki/src/pages/sl/index.astro diff --git a/astro/wiki/src/pages/[...slug].astro b/astro/wiki/src/pages/[...slug].astro index d27194c..23bc196 100644 --- a/astro/wiki/src/pages/[...slug].astro +++ b/astro/wiki/src/pages/[...slug].astro @@ -3,7 +3,7 @@ import fs from "node:fs"; import path from "node:path"; const WIKI_DIR = path.resolve("../../docs/wiki"); -const EXCLUDE = [".git", "sl", "index.md"]; +const EXCLUDE = [".git", "index.md"]; export function getStaticPaths() { function walk(dir, prefix = "") { @@ -48,13 +48,23 @@ if (raw.startsWith("---")) { } } -// Resolve relative wiki links [label](./page.md) → [label](/page/) +// Detect locale from slug prefix +const isSl = slug.startsWith("sl/"); +const locale = isSl ? "sl" : "en"; +const base = isSl ? "/sl/" : "/"; + +// Resolve relative wiki links with locale prefix +// ./page.md → /page/ or /sl/page/ +// ../packaging/x → /../packaging/x (pass through absolute-ish paths) const resolveLinks = (md) => - md.replace(/\]\(\.\/([^)]+)\.md\)/g, "](/$1/)") - .replace(/\]\(\.\.\/([^)]+)\.md\)/g, "](/$1/)"); + md.replace(/\]\(\.\/([^)]+)\.md\)/g, `](${base}$1/)`) + .replace(/\]\(\.\.\/([^)]+)\)/g, "](/$1)"); content = resolveLinks(content); +// Resolve cross-wiki locale links: [label](./sl/page.md) → [/sl/page/] +content = content.replace(/\]\(\.\/sl\/([^)]+)\.md\)/g, "](/sl/$1/)"); + // Render fenced code blocks const renderCode = (md) => md.replace(/```(\w*)\n([\s\S]*?)```/g, (_, lang, code) => { @@ -95,9 +105,14 @@ content = content }); const title = frontmatter.title || slug; + +// Other locale link for language switcher +const otherLocale = isSl ? "en" : "sl"; +const otherSlug = isSl ? slug.replace(/^sl\//, "") : `sl/${slug}`; +const otherLabel = isSl ? "English" : "Slovenščina"; --- - + @@ -106,8 +121,9 @@ const title = frontmatter.title || slug; :root { --bg: #fff; --fg: #1a1a1a; --link: #0366d6; --muted: #666; --border: #e0e0e0; } @media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --fg: #e6e6e6; --link: #58a6ff; --muted: #999; --border: #333; } } body { max-width: 720px; margin: 2rem auto; padding: 0 1rem; font: 16px/1.6 system-ui; background: var(--bg); color: var(--fg); } - nav { margin-bottom: 1.5rem; } + nav { margin-bottom: 1.5rem; display: flex; justify-content: space-between; align-items: baseline; } nav a { color: var(--muted); font-size: .9rem; } + nav .lang a { font-weight: 600; color: var(--link); } h1 { font-size: 1.8rem; } h2 { font-size: 1.4rem; margin-top: 2rem; border-bottom: 1px solid var(--border); padding-bottom: .3rem; } h3 { font-size: 1.1rem; margin-top: 1.5rem; } @@ -122,7 +138,10 @@ const title = frontmatter.title || slug; - +

    {title}

    diff --git a/astro/wiki/src/pages/index.astro b/astro/wiki/src/pages/index.astro index 5e628c2..3a3fddf 100644 --- a/astro/wiki/src/pages/index.astro +++ b/astro/wiki/src/pages/index.astro @@ -3,7 +3,7 @@ import fs from "node:fs"; import path from "node:path"; const WIKI_DIR = path.resolve("../../docs/wiki"); -const EXCLUDE = [".git", "sl", "index.md"]; +const EXCLUDE = [".git", "index.md"]; function walkMarkdown(dir, prefix = "") { const entries = fs.readdirSync(dir, { withFileTypes: true }); @@ -16,16 +16,18 @@ function walkMarkdown(dir, prefix = "") { } else if (e.name.endsWith(".md")) { const rel = prefix ? `${prefix}/${e.name}` : e.name; const slug = rel.replace(/\.md$/, ""); - // Skip frontmatter, grab first H1 as title const raw = fs.readFileSync(full, "utf-8"); const title = raw.match(/^#\s+(.+)$/m)?.[1] || slug; - files.push({ slug, title, file: rel }); + const lang = rel.startsWith("sl/") ? "sl" : "en"; + files.push({ slug, title, file: rel, lang }); } } return files.sort((a, b) => a.title.localeCompare(b.title)); } -const pages = walkMarkdown(WIKI_DIR); +const allPages = walkMarkdown(WIKI_DIR); +const enPages = allPages.filter(p => p.lang === "en"); +const slPages = allPages.filter(p => p.lang === "sl"); --- @@ -38,11 +40,13 @@ const pages = walkMarkdown(WIKI_DIR); @media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --fg: #e6e6e6; --link: #58a6ff; --muted: #999; } } body { max-width: 720px; margin: 2rem auto; padding: 0 1rem; font: 16px/1.6 system-ui; background: var(--bg); color: var(--fg); } h1 { margin-bottom: .25rem; } - p.lede { color: var(--muted); margin-bottom: 1.5rem; } + p.lede { color: var(--muted); margin-bottom: .5rem; } ul { list-style: none; padding: 0; } li { margin: .35rem 0; } a { color: var(--link); text-decoration: none; } a:hover { text-decoration: underline; } + .lang-bar { margin-bottom: 1rem; } + .lang-bar a { font-weight: 600; } @@ -51,8 +55,9 @@ const pages = walkMarkdown(WIKI_DIR); Decision pages — the why behind the architecture. LLM Wiki pattern.

    +

    Slovenščina →

      - {pages.map((p) => ( + {enPages.map((p) => (
    • {p.title}
      • ))}
    diff --git a/astro/wiki/src/pages/sl/index.astro b/astro/wiki/src/pages/sl/index.astro new file mode 100644 index 0000000..99ab775 --- /dev/null +++ b/astro/wiki/src/pages/sl/index.astro @@ -0,0 +1,64 @@ +--- +import fs from "node:fs"; +import path from "node:path"; + +const WIKI_DIR = path.resolve("../../../docs/wiki"); +const EXCLUDE = [".git", "index.md"]; + +function walkMarkdown(dir, prefix = "") { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const files = []; + for (const e of entries) { + if (e.name.startsWith(".") || EXCLUDE.includes(e.name)) continue; + const full = path.join(dir, e.name); + if (e.isDirectory()) { + files.push(...walkMarkdown(full, prefix ? `${prefix}/${e.name}` : e.name)); + } else if (e.name.endsWith(".md")) { + const rel = prefix ? `${prefix}/${e.name}` : e.name; + const slug = rel.replace(/\.md$/, ""); + const raw = fs.readFileSync(full, "utf-8"); + const title = raw.match(/^#\s+(.+)$/m)?.[1] || slug; + if (rel.startsWith("sl/")) { + files.push({ slug: slug.replace(/^sl\//, ""), title, file: rel }); + } + } + } + return files.sort((a, b) => a.title.localeCompare(b.title)); +} + +const pages = walkMarkdown(WIKI_DIR); +--- + + + + + + Colibri Wiki + + + +

    Colibri Wiki

    +

    + Strani z odločitvami — zakaj je arhitektura takšna, kot je. + Vzorec LLM Wiki. +

    +

    ← English

    + + + -- 2.45.3 From 3acb9911969239b072f02e51a91335a2e4b4dd45 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 12:04:37 +0200 Subject: [PATCH 10/19] =?UTF-8?q?docs(sl):=20fix=20quality-gates=20?= =?UTF-8?q?=E2=80=94=20vrata=E2=86=92preverjanje,=20krajevni=E2=86=92lokal?= =?UTF-8?q?ni?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Vrata" is a correct translation for TCP/network ports, but wrong for software quality gates. Changes: quality-gates.md — rewritten: "kakovostno preverjanje" not "kakovostna vrata" vrata → preverjanje (gate → verification) krajevna → lokalno (local) kljuka → kavelj (door handle → git hook) padejo → spodleti (falls → fails) Scattered fixes in 5 other files: cost-model.md, index.md, mother-hive.md, naming-decisions.md, store-schema.md — vrata → preverjanje/dovoljenja external-mcp.md — vrata → dovoljenja (permissions) Kept: "vrata" for TCP ports (correct), "vhodna vrata" for front-door metaphor (works in Slovenian), "vrata za poslušanje" for listening port. Also fixed: frontmatter quoting for YAML (nested quotes, colons). --- docs/wiki/sl/agent-events-reference.md | 2 +- docs/wiki/sl/agent-harness.md | 4 +-- docs/wiki/sl/contracts.md | 2 +- docs/wiki/sl/cost-model.md | 4 +-- docs/wiki/sl/deployment.md | 2 +- docs/wiki/sl/external-mcp.md | 2 +- docs/wiki/sl/glasspane.md | 2 +- docs/wiki/sl/headroom-sidecar.md | 2 +- docs/wiki/sl/index.md | 6 ++--- docs/wiki/sl/jail-confinement.md | 2 +- docs/wiki/sl/layered-soul.md | 2 +- docs/wiki/sl/mother-hive.md | 4 +-- docs/wiki/sl/naming-decisions.md | 4 +-- docs/wiki/sl/operator-attention.md | 4 +-- docs/wiki/sl/operator-cli.md | 2 +- docs/wiki/sl/quality-gates.md | 36 +++++++++++++------------- docs/wiki/sl/runtime-inventory.md | 2 +- docs/wiki/sl/skills-catalog.md | 2 +- docs/wiki/sl/store-schema.md | 6 ++--- docs/wiki/sl/task-board.md | 2 +- docs/wiki/sl/terminal.md | 2 +- docs/wiki/sl/tui.md | 2 +- docs/wiki/sl/vault-provision.md | 2 +- 23 files changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/wiki/sl/agent-events-reference.md b/docs/wiki/sl/agent-events-reference.md index 1fc9a56..ff1f688 100644 --- a/docs/wiki/sl/agent-events-reference.md +++ b/docs/wiki/sl/agent-events-reference.md @@ -1,6 +1,6 @@ --- title: Referenca agentskih dogodkov -description: Referenca dogodkov po opremi za zot in pi, preslikave Glasspane in preverjena polja prepisa. +description: "Referenca dogodkov po opremi za zot in pi, preslikave Glasspane in preverjena polja prepisa." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/agent-harness.md b/docs/wiki/sl/agent-harness.md index b936de4..e09f1ef 100644 --- a/docs/wiki/sl/agent-harness.md +++ b/docs/wiki/sl/agent-harness.md @@ -1,6 +1,6 @@ --- -title: Agentska oprema: zot + Colibri -description: Dve binarni datoteki, ne ena — zot (agent, Go) in Colibri (krmilna ravnina, Rust). +title: "Agentska oprema: zot + Colibri" +description: "Dve binarni datoteki, ne ena — zot (agent, Go) in Colibri (krmilna ravnina, Rust)." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/contracts.md b/docs/wiki/sl/contracts.md index 092d77f..79027f3 100644 --- a/docs/wiki/sl/contracts.md +++ b/docs/wiki/sl/contracts.md @@ -1,6 +1,6 @@ --- title: Stabilne JSON pogodbe -description: Jezikovno neodvisne oblike na žici, v skupni rabi med Colibri (Rust) in Clawdie agenti (TypeScript). +description: "Jezikovno neodvisne oblike na žici, v skupni rabi med Colibri (Rust) in Clawdie agenti (TypeScript)." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/cost-model.md b/docs/wiki/sl/cost-model.md index 17641c6..eea994b 100644 --- a/docs/wiki/sl/cost-model.md +++ b/docs/wiki/sl/cost-model.md @@ -1,6 +1,6 @@ --- title: Model stroškov -description: Kako Colibri sledi vsakemu žetonu, meri zadetke predpomnilnika in samodejno stopnjuje med cenovnimi načini. +description: "Kako Colibri sledi vsakemu žetonu, meri zadetke predpomnilnika in samodejno stopnjuje med cenovnimi načini." --- ← [kazalo](./index.md) @@ -94,4 +94,4 @@ odgovori, neodvisno od tega, kako je bila zahteva izvedena. - [task-board](./task-board.md) — razporejevalnik, ki razpošilja opravila znotraj proračunov sej - [mother-hive](./mother-hive.md) — arhitektura MCP (druga stroškovna domena) -- [quality-gates](./quality-gates.md) — vrata, ki preverjajo razčlenjevanje cenovnih načinov +- [quality-gates](./quality-gates.md) — preverjanje, ki preverja razčlenjevanje cenovnih načinov diff --git a/docs/wiki/sl/deployment.md b/docs/wiki/sl/deployment.md index cf29329..238a47a 100644 --- a/docs/wiki/sl/deployment.md +++ b/docs/wiki/sl/deployment.md @@ -1,6 +1,6 @@ --- title: Namestitev -description: Nameščevalnik gostitelja clawdie — odkrije ZFS, pripravi podatkovne zbirke, ustvari uporabnika storitve in namesti enoto rc.d/systemd. +description: "Nameščevalnik gostitelja clawdie — odkrije ZFS, pripravi podatkovne zbirke, ustvari uporabnika storitve in namesti enoto rc.d/systemd." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/external-mcp.md b/docs/wiki/sl/external-mcp.md index 0a9cc39..53a51d5 100644 --- a/docs/wiki/sl/external-mcp.md +++ b/docs/wiki/sl/external-mcp.md @@ -1,6 +1,6 @@ --- title: Zunanji MCP -description: Most MCP za urejevalnike in zunanje gostitelje — branje, pisanje in vrata za zunanje klice prek Colibrijeve implementacije MCP. +description: "Most MCP za urejevalnike in zunanje gostitelje — branje, pisanje in dovoljenja za zunanje klice prek Colibrijeve implementacije MCP." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/glasspane.md b/docs/wiki/sl/glasspane.md index ced9ac8..32ab29d 100644 --- a/docs/wiki/sl/glasspane.md +++ b/docs/wiki/sl/glasspane.md @@ -1,6 +1,6 @@ --- title: Glasspane — nadzor stanja agentov -description: Colibrijeva plast za opazovanje agentov. Gleda podprocese agentov prek JSONL, zlaga tok v semantični avtomat stanj in izpostavlja API posnetkov. +description: "Colibrijeva plast za opazovanje agentov. Gleda podprocese agentov prek JSONL, zlaga tok v semantični avtomat stanj in izpostavlja API posnetkov." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/headroom-sidecar.md b/docs/wiki/sl/headroom-sidecar.md index bd45985..afeee3a 100644 --- a/docs/wiki/sl/headroom-sidecar.md +++ b/docs/wiki/sl/headroom-sidecar.md @@ -1,6 +1,6 @@ --- title: Stranski vagon Headroom -description: Colibri lahko neobvezno prosi krajevni stranski vagon headroom-ai, da stisne rezultate orodij, preden dosežejo proračun žetonov. +description: "Colibri lahko neobvezno prosi krajevni stranski vagon headroom-ai, da stisne rezultate orodij, preden dosežejo proračun žetonov." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/index.md b/docs/wiki/sl/index.md index 6e006d2..26ac56a 100644 --- a/docs/wiki/sl/index.md +++ b/docs/wiki/sl/index.md @@ -1,6 +1,6 @@ --- title: Colibri Wiki -description: Zbirka znanja o odločitvah in arhitekturi Colibri — utemeljitve, ki jih koda ne more izraziti. +description: "Zbirka znanja o odločitvah in arhitekturi Colibri — utemeljitve, ki jih koda ne more izraziti." --- Zbirka znanja o Colibrijevih **odločitvah in arhitekturi** — po vzoru @@ -62,10 +62,10 @@ clippy. | [naming-decisions](./naming-decisions.md) | Imenik preimenovanj, nevtralnih glede na opremo / arhitekturnih — dostavljenih in v teku | | [layered-soul](./layered-soul.md) | Kako Colibri danes uporablja repozitorij pregledanega konteksta layered-soul proti načrtovanemu | | [task-board](./task-board.md) | Točkovanje po zmožnostih, cron razporejanje, praznjenje vnosne vrste, podlaga SQLite | -| [quality-gates](./quality-gates.md) | `ci-checks.sh` kot vrata pred združitvijo; zakaj je odmik prej dosegel `main` | +| [quality-gates](./quality-gates.md) | `ci-checks.sh` kot preverjanje pred združitvijo; zakaj je odmik prej dosegel `main` | | [contracts](./contracts.md) | Stabilne JSON sheme (run-manifest, runtime-inventory, provider-smoke), zlati testi | | [store-schema](./store-schema.md) | Usklajevalna shema SQLite in disciplina migracij | -| [external-mcp](./external-mcp.md) | Most MCP za urejevalnike + zunanji gostitelj stdio MCP; vrata za branje/pisanje/zunanji-klic | +| [external-mcp](./external-mcp.md) | Most MCP za urejevalnike + zunanji gostitelj stdio MCP; dovoljenja za branje/pisanje/zunanji-klic | | [operator-cli](./operator-cli.md) | CLI `colibri` kot tanek tipiziran odjemalec Unix vtičnice prek API demona | | [tui](./tui.md) | Odjemalec terminalske nadzorne plošče (colibri-tui) proti avtomatu stanj colibri-glasspane | | [terminal](./terminal.md) | Odločitev o terminalski zmožnosti (Kitty, razširjeno poročanje tipk, prehod tmux, SSH terminfo) | diff --git a/docs/wiki/sl/jail-confinement.md b/docs/wiki/sl/jail-confinement.md index 7bfd6ce..f72f5ef 100644 --- a/docs/wiki/sl/jail-confinement.md +++ b/docs/wiki/sl/jail-confinement.md @@ -1,6 +1,6 @@ --- title: Omejitev ječ -description: Trajne proti prehodnim ječam, pravilnik načina priv in ponovna uporaba omejitve zaganjalnika za strežnike MCP. +description: "Trajne proti prehodnim ječam, pravilnik načina priv in ponovna uporaba omejitve zaganjalnika za strežnike MCP." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/layered-soul.md b/docs/wiki/sl/layered-soul.md index 4440653..137ff89 100644 --- a/docs/wiki/sl/layered-soul.md +++ b/docs/wiki/sl/layered-soul.md @@ -1,6 +1,6 @@ --- title: Integracija plastovite duše -description: Kako Colibri danes uporablja repozitorij layered-soul in kaj je še načrtovano. +description: "Kako Colibri danes uporablja repozitorij layered-soul in kaj je še načrtovano." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/mother-hive.md b/docs/wiki/sl/mother-hive.md index d3cd291..1c07b0f 100644 --- a/docs/wiki/sl/mother-hive.md +++ b/docs/wiki/sl/mother-hive.md @@ -1,6 +1,6 @@ --- title: Matični hive -description: Kako matično vozlišče (OSA) usklajuje USB-operaterska vozlišča prek MCP prek SSH → PostgreSQL. +description: "Kako matično vozlišče (OSA) usklajuje USB-operaterska vozlišča prek MCP prek SSH → PostgreSQL." --- ← [kazalo](./index.md) @@ -116,4 +116,4 @@ datoteke ali `sudo`. - [agent-harness](./agent-harness.md) — razcep zot/Colibri; samodejni zagon - [naming-decisions](./naming-decisions.md) — `usb_nodes → hive_nodes`, preimenovanje zastavice autospawn -- [quality-gates](./quality-gates.md) — vrata, ki bi morala ujeti odmik ob času PR +- [quality-gates](./quality-gates.md) — preverjanje, ki bi moralo ujeti odmik ob času PR diff --git a/docs/wiki/sl/naming-decisions.md b/docs/wiki/sl/naming-decisions.md index 60306d7..0620a38 100644 --- a/docs/wiki/sl/naming-decisions.md +++ b/docs/wiki/sl/naming-decisions.md @@ -1,6 +1,6 @@ --- title: Imenik odločitev o poimenovanju -description: Živa evidenca preimenovanj, ki so jih pognale presežene predpostavke — da je prihodnji odmik preverljiv proti enemu seznamu. +description: "Živa evidenca preimenovanj, ki so jih pognale presežene predpostavke — da je prihodnji odmik preverljiv proti enemu seznamu." --- ← [kazalo](./index.md) @@ -60,4 +60,4 @@ _Trenutno nobeno._ ## Glej tudi - [agent-harness](./agent-harness.md) -- [quality-gates](./quality-gates.md) — vrata, ki bi morala te ujeti ob času PR +- [quality-gates](./quality-gates.md) — preverjanje, ki bi moralo te ujeti ob času PR diff --git a/docs/wiki/sl/operator-attention.md b/docs/wiki/sl/operator-attention.md index c1523f9..ef85c03 100644 --- a/docs/wiki/sl/operator-attention.md +++ b/docs/wiki/sl/operator-attention.md @@ -1,6 +1,6 @@ --- -title: Operaterska pozornost — "ali ta agent potrebuje mene zdaj?" -description: Kako Glasspane presoja, kateri agent potrebuje operaterski poseg, in to prikaže v TUI. +title: "Operaterska pozornost — ali ta agent potrebuje mene zdaj?" +description: "Kako Glasspane presoja, kateri agent potrebuje operaterski poseg, in to prikaže v TUI." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/operator-cli.md b/docs/wiki/sl/operator-cli.md index 0bfb0a9..1433083 100644 --- a/docs/wiki/sl/operator-cli.md +++ b/docs/wiki/sl/operator-cli.md @@ -1,6 +1,6 @@ --- title: Operaterski CLI (`colibri`) -description: Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona — tanek tipiziran odjemalec Unix vtičnice. +description: "Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona — tanek tipiziran odjemalec Unix vtičnice." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/quality-gates.md b/docs/wiki/sl/quality-gates.md index 930dade..f69d16f 100644 --- a/docs/wiki/sl/quality-gates.md +++ b/docs/wiki/sl/quality-gates.md @@ -1,50 +1,50 @@ --- -title: Kakovostna vrata -description: Sprememba ni "končana", dokler krajevna vrata ne uspejo — cargo fmt, clippy, cargo test, markdown vrata, wiki-lint. +title: Kakovostno preverjanje +description: 'Sprememba ni končana brez uspešnega lokalnega preverjanja — cargo fmt, clippy, cargo test, markdown, wiki-lint.' --- ← [kazalo](./index.md) ## Odločitev -Sprememba ni "končana", dokler krajevna vrata ne uspejo: +Sprememba ni "končana", dokler ne prestane lokalnega preverjanja: ```sh ./scripts/ci-checks.sh # cargo fmt --check, clippy -D warnings, cargo test, markdown gate, wiki-lint --strict ``` -Predpotisna kljuka (`scripts/pre-push`) zažene ta ista vrata ob vsakem +Predpotisni kavelj (`scripts/pre-push`) zažene isto preverjanje ob vsakem `git push` na `main` — aktiviraj enkrat na klon z `./scripts/install-hooks.sh`. -Kljuka zavrne potisk, če katerakoli vrata padejo; obidi samo v sili z +Kavelj zavrne potisk, če katerokoli preverjanje spodleti; obidi samo v sili z `--no-verify`. `.forgejo/workflows/ci.yml` kodira ista preverjanja, vendar **noben izvajalnik Forgejo Actions ni registriran**, zato nič ne uveljavlja preverjanj -strežniško. Dokler izvajalnik ni aktiven, so krajevna vrata + predpotisna -kljuka uveljavitvena plast. Navedeno kot obvezno v `AGENTS.md`. +strežniško. Dokler izvajalnik ni aktiven, sta lokalno preverjanje + predpotisni +kavelj uveljavitvena plast. Navedeno kot obvezno v `AGENTS.md`. ## Zakaj ta stran obstaja Napaka pri prevajanju (`pi_binary` nedefiniran, iz napol dokončanega -preimenovanja) je dosegla `main`, ker so bila vrata preskočena _in_ -neuveljavljena. Ista revizija je ugotovila, da so bila oboja vrata takrat -dejansko rdeča na `main`: +preimenovanja) je dosegla `main`, ker je bilo preverjanje preskočeno _in_ +neuveljavljeno. Ista revizija je ugotovila, da sta bili obe preverjanji takrat +dejansko rdeči na `main`: -- `clippy -D warnings` je padel na predobstoječem lintu → Rust vrata bi - padla za vsakogar, ki bi jih zagnal. -- markdown vrata so padla na prettier-umazanih dokumentih. +- `clippy -D warnings` je padel na predobstoječem lintu → Rust preverjanje bi + padlo za vsakogar, ki bi ga zagnal. +- markdown preverjanje je padlo na prettier-umazanih dokumentih. -Oboje je bilo spravljeno v zeleno, zato so vrata zdaj dejansko zagonljiva. -Nauk: vrata, ki jih nihče ne poganja (in so tako ali tako rdeča), so -korenski vzrok, da odmik doseže `main` — bolj kot vsak posamezen spodrsljaj -pri poimenovanju. +Oboje je bilo spravljeno v zeleno, zato je preverjanje zdaj dejansko +zagonljivo. Nauk: preverjanje, ki ga nihče ne poganja (in je tako ali tako +rdeče), je korenski vzrok, da odmik doseže `main` — bolj kot vsak posamezen +spodrsljaj pri poimenovanju. ## Odnos do tega wikija Imenik [naming-decisions](./naming-decisions.md) + `wiki-lint --strict` sta _pomenska_ protiutež `ci-checks.sh`: prevajalnik/clippy ujameta zlomljeno _kodo_, ne pa dokumenta, ki še vedno opisuje staro zasnovo, ali imena, ki je -odneslo. Wiki lint pokriva to vrzel. Zdaj je del obveznih vrat — napaka +odneslo. Wiki lint pokriva to vrzel. Zdaj je del obveznega preverjanja — napaka odmika blokira potisk, enako kot opozorilo clippy. ## Glej tudi diff --git a/docs/wiki/sl/runtime-inventory.md b/docs/wiki/sl/runtime-inventory.md index 825dfeb..f801a18 100644 --- a/docs/wiki/sl/runtime-inventory.md +++ b/docs/wiki/sl/runtime-inventory.md @@ -1,6 +1,6 @@ --- title: Popis izvajalnega okolja -description: Bralnik stanja gostitelja — aditivne, bralne integracije, ki zbirajo različice OS, paketov in izvajalnega okolja. +description: "Bralnik stanja gostitelja — aditivne, bralne integracije, ki zbirajo različice OS, paketov in izvajalnega okolja." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/skills-catalog.md b/docs/wiki/sl/skills-catalog.md index 151c5b3..136c300 100644 --- a/docs/wiki/sl/skills-catalog.md +++ b/docs/wiki/sl/skills-catalog.md @@ -1,6 +1,6 @@ --- title: Katalog veščin -description: Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI — uvozi SKILL.md v Colibrijevo tabelo skills. +description: "Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI — uvozi SKILL.md v Colibrijevo tabelo skills." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/store-schema.md b/docs/wiki/sl/store-schema.md index 022fb67..d47ac18 100644 --- a/docs/wiki/sl/store-schema.md +++ b/docs/wiki/sl/store-schema.md @@ -1,6 +1,6 @@ --- title: Shema shrambe -description: Koordinacijska shramba Colibri — ena sama podatkovna zbirka SQLite, ki hrani tablo opravil, register agentov in veščin ter preslikavo najemnikov. +description: "Koordinacijska shramba Colibri — ena sama podatkovna zbirka SQLite, ki hrani tablo opravil, register agentov in veščin ter preslikavo najemnikov." --- ← [kazalo](./index.md) @@ -69,8 +69,8 @@ svojem `tenant_id` v ukazih vtičnice in kljukah za oskrbo. ### Omejitev CHECK stanja opravila je vir resnice `tasks.status` je omejen na `('queued','claimed','started','done','failed')`. -Enum `TaskStatus` v Rustu ga zrcali, vendar je podatkovna zbirka zadnja -vrata. Ukaz, ki poskusi vstaviti neznano stanje, pade ob času pisanja. +Enum `TaskStatus` v Rustu ga zrcali, vendar je podatkovna zbirka zadnje +preverjanje. Ukaz, ki poskusi vstaviti neznano stanje, pade ob času pisanja. → `crates/colibri-store/src/schema.rs` diff --git a/docs/wiki/sl/task-board.md b/docs/wiki/sl/task-board.md index 0d6d317..7a62578 100644 --- a/docs/wiki/sl/task-board.md +++ b/docs/wiki/sl/task-board.md @@ -1,6 +1,6 @@ --- title: Tabla opravil + razporejevalnik -description: Kako Colibri hrani operaterska opravila in jih razporeja med agente glede na zmožnosti. +description: "Kako Colibri hrani operaterska opravila in jih razporeja med agente glede na zmožnosti." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/terminal.md b/docs/wiki/sl/terminal.md index 572d9e7..d842bd0 100644 --- a/docs/wiki/sl/terminal.md +++ b/docs/wiki/sl/terminal.md @@ -1,6 +1,6 @@ --- title: Terminal — zmožnost, ne znamka -description: Zmožnost terminala kot ozka, prenosljiva abstrakcija — Kitty, ne iTerm2; ANSI, ne lastniški protokoli. +description: "Zmožnost terminala kot ozka, prenosljiva abstrakcija — Kitty, ne iTerm2; ANSI, ne lastniški protokoli." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/tui.md b/docs/wiki/sl/tui.md index 9966637..1ad0aa6 100644 --- a/docs/wiki/sl/tui.md +++ b/docs/wiki/sl/tui.md @@ -1,6 +1,6 @@ --- title: Terminalska nadzorna plošča (colibri-tui) -description: Colibrijeva živa terminalska nadzorna plošča — povezuje se na Unix vtičnico demona in prikazuje agente, stanja ter pozornostna opozorila. +description: "Colibrijeva živa terminalska nadzorna plošča — povezuje se na Unix vtičnico demona in prikazuje agente, stanja ter pozornostna opozorila." --- ← [kazalo](./index.md) diff --git a/docs/wiki/sl/vault-provision.md b/docs/wiki/sl/vault-provision.md index 51429b7..0c1f048 100644 --- a/docs/wiki/sl/vault-provision.md +++ b/docs/wiki/sl/vault-provision.md @@ -1,6 +1,6 @@ --- title: Oskrba trezorja -description: Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta — preslikava najemnik → ječa → zbirka. +description: "Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta — preslikava najemnik → ječa → zbirka." --- ← [kazalo](./index.md) -- 2.45.3 From 9643790739a003a609257a13e6d7ffc71952e78c Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 12:16:27 +0200 Subject: [PATCH 11/19] skill(nginx): document SSL cert placeholder + ACME challenge ordering hiccups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three hiccups from the wiki.clawdie.si deployment (26.jun.2026): 1. Placeholder cert — nginx refuses to start when ssl_certificate files dont exist yet. Create a temporary self-signed cert first, then acme.sh --issue overwrites it with the real cert. 2. ACME challenge location ordering — nginx matches location blocks in order. .well-known/acme-challenge/ MUST come before the location / { return 301 https://... } redirect, otherwise ACME validation returns 301 instead of the challenge file. 3. acme.sh --key-file + --fullchain-file — these flags write directly to the nginx SSL paths, replacing the placeholder. The cert paths must match between nginx config and acme.sh invocation. New "Adding a new public static HTTPS site — full flow" section covers the complete pattern: DNS first → placeholder cert → vhost with ordered locations → real cert → content deploy → renewal. Two new troubleshooting entries: BIO_new_file() failed (missing cert), ACME challenge 404/301 (location ordering or missing directory). --- .agent/nginx/SKILL.md | 677 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 677 insertions(+) create mode 100644 .agent/nginx/SKILL.md diff --git a/.agent/nginx/SKILL.md b/.agent/nginx/SKILL.md new file mode 100644 index 0000000..04952a7 --- /dev/null +++ b/.agent/nginx/SKILL.md @@ -0,0 +1,677 @@ +--- +name: nginx +description: Manage nginx web serving for the cms jail on FreeBSD. Host nginx terminates SSL and proxies to jail nginx at ${AGENT_SUBNET_BASE}.4. Use when configuring vhosts, SSL, static site serving, or Strapi reverse proxy. Triggers on "nginx", "website", "vhost", "update site", "add vhost", "ssl". +--- + +# Nginx + +Use this skill for nginx decisions on the **cms jail** (`${AGENT_SUBNET_BASE}.4`) and the **host nginx** SSL proxy layer. + +## Current surface model + +- Operator app: `ai.` — not served by cms jail nginx +- Shared CMS admin/API: `cms.` — shared service surface +- Shared code admin: `git.` — separate service surface, not cms nginx +- Tenant home: `.` — served by cms jail nginx +- Tenant site: `..` — served by cms jail nginx + +For the internal default install, `` is `home.arpa`. + +## Actual architecture (as deployed) + +```text +operator at ai. + → controlplane app (not cms nginx) + +tenant/browser at . or .. + → host nginx (optional public SSL terminator / proxy) + → cms jail nginx at ${AGENT_SUBNET_BASE}.4 + → tenant home + tenant sites (static output) + +operator/editor at cms. + → host nginx (optional public/internal proxy) + → cms jail nginx + → Strapi admin + CMS API +``` + +**Host nginx** terminates SSL and proxies to the jail when public exposure exists. +**Jail nginx** is the real web server for tenant homes, tenant sites, and the shared CMS surface. + +This diverges from the original design (PF RDR → jail nginx handling SSL itself). The reason: +host nginx was already running for clawdie.si, so PF RDR to the jail would break the existing +site. Host-proxy is the correct pattern when multiple domains share the same host. + +## Scope + +This skill covers: + +- Host nginx SSL proxy vhosts (SSL termination, proxy_pass to jail) +- Jail nginx server_name routing for `cms.`, `.`, and `..` +- SSL certificate management for public-exposed surfaces +- ACME challenge pattern when host nginx proxies to jail +- Strapi admin/API reverse proxy on the shared CMS surface +- Tenant home and tenant-site static serving + +This skill does not replace: + +- `warden-pf` for PF firewall rules +- `freebsd-admin` for host-level system changes + +## SSL certificate tools (two tools on this host) + +| Domain | Tool | Location | +| ------------------------------------------------------- | ------- | ------------------------------------------- | +| `clawdie.si`, `docs.clawdie.si`, `osa.smilepowered.org` | acme.sh | `/root/.acme.sh/_ecc/` | +| `samob.smilepowered.org` | certbot | `/usr/local/etc/letsencrypt/live//` | + +Keep the tools separate. Do not migrate certbot domains to acme.sh without a plan. + +`just doctor` audits the canonical acme.sh-backed public cert paths and reports `TLS_