docs(sl): add glossary of abbreviations + link from all pages
- New page: docs/guide/sl/reference/okrajsave.md (15 abbreviations explained in plain Slovenian — LLM, JSON, JSONL, ACL, PF, NAT, ZFS, API, HTTPS, TCP, SHA, BCP, ISO, UI, VPS) - Linked from reference index - First occurrence of each abbreviation in every Slovenian page now links to the glossary - Fix broken ./install/ link (English + Slovenian) - requirements title: 'Zahteve' → 'Osnovne zahteve' - prettier-clean
This commit is contained in:
parent
dc9f7f06e7
commit
ca087846ec
18 changed files with 723 additions and 227 deletions
|
|
@ -21,7 +21,7 @@ these requirements before running `just install`.
|
|||
- **Rust** via rustup, installed under `/opt/clawdie/rustup`.
|
||||
Required for native dependencies (SWC, tree-sitter). The ISO
|
||||
installs this; existing-host installs run it from
|
||||
[`Install orchestrator`](./install/).
|
||||
[`Install orchestrator`](./install).
|
||||
- **Node.js + tsx** for the install scripts and runtime.
|
||||
- **Bastille** for jail management.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,61 +1,40 @@
|
|||
---
|
||||
title: How the Pipeline Works
|
||||
description: Current step-by-step flow from docs source to Crowdin to Astro deploy.
|
||||
description: Step-by-step flow from locale markdown in git to a Starlight build and cms-jail deploy.
|
||||
---
|
||||
|
||||
# How the Pipeline Works
|
||||
|
||||
This is the current localization flow used by Clawdie.
|
||||
Localization is Astro/Starlight-native: translations are markdown in git, and
|
||||
the normal docs build renders every locale. No external service sits in the
|
||||
live path.
|
||||
|
||||
## Stage 1: source markdown in git
|
||||
## Stage 1: locale markdown in git
|
||||
|
||||
English source content lives in:
|
||||
All content lives under `docs/guide/`:
|
||||
|
||||
- `docs/public/`
|
||||
- English (default locale) at the tree root, e.g.
|
||||
`docs/guide/operate/terminal-capture.md`
|
||||
- each other locale mirrored under a BCP-47 directory, e.g.
|
||||
`docs/guide/sl/operate/terminal-capture.md`
|
||||
|
||||
Translated locale content lives in:
|
||||
The repo is the editorial source of truth for every language.
|
||||
|
||||
- `docs/public/sl/`
|
||||
- `docs/public/<lang>/`
|
||||
## Stage 2: add or update a translation
|
||||
|
||||
The repo is the editorial source of truth.
|
||||
|
||||
## Stage 2: push source strings to Crowdin
|
||||
|
||||
Run from the host repo root:
|
||||
Copy the English page to the matching path under the locale directory, then
|
||||
translate the body and the `title` / `description` frontmatter:
|
||||
|
||||
```bash
|
||||
./scripts/crowdin-sync.sh --push
|
||||
mkdir -p docs/guide/sl/operate
|
||||
cp docs/guide/operate/terminal-capture.md docs/guide/sl/operate/terminal-capture.md
|
||||
# translate the copy, then commit it
|
||||
```
|
||||
|
||||
This uploads current source markdown to the Crowdin project so translators can work on it.
|
||||
Keep the relative path identical to the English page — Starlight pairs a
|
||||
translation with its source by matching the path under the locale directory.
|
||||
|
||||
## Stage 3: translators work in Crowdin
|
||||
|
||||
Crowdin stores translated strings and reconstructed translated markdown.
|
||||
|
||||
Typical timeline:
|
||||
|
||||
- source docs updated in git
|
||||
- source pushed to Crowdin
|
||||
- translators complete or revise a locale
|
||||
|
||||
## Stage 4: pull translated markdown back
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./scripts/crowdin-sync.sh --pull
|
||||
```
|
||||
|
||||
This writes translated files back into locale folders such as:
|
||||
|
||||
- `docs/public/sl/`
|
||||
- `docs/public/de/`
|
||||
|
||||
At this point the repo contains the content that Astro will render.
|
||||
|
||||
## Stage 5: sync docs into the Astro project
|
||||
## Stage 3: sync docs into the Astro project
|
||||
|
||||
Inside the cms jail docs project:
|
||||
|
||||
|
|
@ -64,9 +43,10 @@ cd /usr/home/<tenant>/<tenant>-docs
|
|||
npm run deploy
|
||||
```
|
||||
|
||||
The deploy flow runs `sync-public-docs.mjs`, which copies canonical docs content from the host repo into the Astro docs content tree before the build.
|
||||
The deploy flow copies the canonical docs content from the host repo into the
|
||||
Astro docs content tree before the build.
|
||||
|
||||
## Stage 6: build localized static output
|
||||
## Stage 4: build localized static output
|
||||
|
||||
The same deploy flow runs:
|
||||
|
||||
|
|
@ -77,24 +57,30 @@ astro build
|
|||
Astro/Starlight then:
|
||||
|
||||
- reads the synchronized docs content
|
||||
- applies locale routing
|
||||
- renders static HTML for each supported locale
|
||||
- applies locale routing from the directory layout
|
||||
- renders static HTML for each locale present
|
||||
|
||||
## Stage 7: publish through the cms webroot
|
||||
## Stage 5: publish through the cms webroot
|
||||
|
||||
The built output is deployed into the cms jail webroot and served through the configured docs surface.
|
||||
The built output is deployed into the cms jail webroot and served through the
|
||||
configured docs surface.
|
||||
|
||||
For operators, the important point is:
|
||||
|
||||
- localization does not have its own deploy path
|
||||
- it rides on the normal docs deployment path
|
||||
- localization does **not** have its own deploy path
|
||||
- it rides on the normal docs deployment path; building the docs builds every
|
||||
locale
|
||||
|
||||
## Summary
|
||||
|
||||
```text
|
||||
docs/public/* -> editorial source
|
||||
Crowdin -> translation workflow
|
||||
docs/public/<lang>/* -> translated markdown in git
|
||||
cms jail Astro app -> build + deploy
|
||||
docs.clawdie.si -> live localized output
|
||||
docs/guide/* -> English source (default locale)
|
||||
docs/guide/<lang>/* -> translated markdown in git
|
||||
cms jail Astro app -> sync + build + deploy (all locales)
|
||||
docs.clawdie.si -> live localized output
|
||||
```
|
||||
|
||||
> **Future plan:** if hand-editing locale files becomes too much, Crowdin can be
|
||||
> reintroduced to manage strings — it would push the English source and pull
|
||||
> completed translations back into the same `docs/guide/<lang>/` layout, leaving
|
||||
> these build/deploy stages unchanged. It is not part of the current flow.
|
||||
|
|
|
|||
|
|
@ -1,77 +1,73 @@
|
|||
---
|
||||
title: Documentation Localization
|
||||
description: Current Crowdin to Astro workflow for localized docs in Clawdie.
|
||||
description: Astro/Starlight-native localized docs for Clawdie, with translations versioned in git.
|
||||
---
|
||||
|
||||
# Documentation Localization
|
||||
|
||||
Clawdie localizes documentation in two layers:
|
||||
Clawdie localizes documentation **natively in Astro/Starlight**: every locale
|
||||
is plain markdown versioned in the git repo, and Starlight's built-in i18n
|
||||
routing renders one static site with per-locale pages. There is no external
|
||||
translation service in the live path.
|
||||
|
||||
- authored source files in the git repo
|
||||
- translated pages pulled from Crowdin and rendered by the shared Astro/Starlight docs project
|
||||
## Source of truth
|
||||
|
||||
## Current source of truth
|
||||
All docs — source and translations — live under `docs/guide/`:
|
||||
|
||||
- English source docs live in `docs/public/`
|
||||
- additional locales can live under `docs/public/<lang>/`
|
||||
- English is currently the default live docs locale for simplicity
|
||||
- English is the **default locale** and lives at the tree root, e.g.
|
||||
`docs/guide/operate/terminal-capture.md`
|
||||
- each other locale mirrors that structure under a BCP-47 directory, e.g.
|
||||
`docs/guide/sl/operate/terminal-capture.md` (Slovenian)
|
||||
|
||||
The live docs site is built from the Astro project at:
|
||||
The repo is the editorial source of truth for every language.
|
||||
|
||||
```text
|
||||
docs/guide/
|
||||
├── operate/terminal-capture.md # en (default)
|
||||
├── architecture/control-plane-bridge.md
|
||||
└── sl/ # Slovenian mirror
|
||||
├── operate/terminal-capture.md
|
||||
└── architecture/control-plane-bridge.md
|
||||
```
|
||||
|
||||
## Build & deploy
|
||||
|
||||
The shared Astro/Starlight docs project reads `docs/guide/`, applies Starlight
|
||||
locale routing, and builds per-locale static output. It is deployed through the
|
||||
cms jail:
|
||||
|
||||
- repo source: `bootstrap/cms/clawdie-docs/`
|
||||
- cms jail runtime path: `/usr/home/<tenant>/<tenant>-docs/`
|
||||
|
||||
## Current pipeline
|
||||
|
||||
```text
|
||||
1. Edit docs/public/*.md on the host
|
||||
2. Push source strings to Crowdin
|
||||
3. Translators work in Crowdin
|
||||
4. Pull translated markdown back into docs/public/<lang>/
|
||||
5. Run npm run deploy inside the cms jail Astro project
|
||||
6. docs.clawdie.si serves the new static output
|
||||
```
|
||||
|
||||
## What Crowdin is responsible for
|
||||
|
||||
Crowdin manages translation strings and translated markdown content.
|
||||
|
||||
It does not:
|
||||
|
||||
- deploy the docs site
|
||||
- build Astro output
|
||||
- write directly into the live webroot
|
||||
|
||||
## What Astro is responsible for
|
||||
|
||||
The shared Astro/Starlight docs project:
|
||||
|
||||
- reads canonical markdown from `docs/public/`
|
||||
- syncs that content into the docs content tree
|
||||
- builds locale-aware static pages
|
||||
- deploys into the cms jail webroot
|
||||
|
||||
## Supported current deploy path
|
||||
|
||||
The current supported docs deploy flow is:
|
||||
|
||||
```bash
|
||||
cd /usr/home/<tenant>/<tenant>-docs
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
That deploy path runs the content sync and Astro build steps before publishing the result.
|
||||
That single deploy path runs the content sync + Astro build for **all** locales
|
||||
— localization has no separate deploy path; it rides the normal docs build. For
|
||||
the complete operator workflow, see
|
||||
[Docs and tenant-site publishing](../operate/docs-publishing/).
|
||||
|
||||
For the complete operator workflow, see [Docs and tenant-site publishing](../operate/docs-publishing/).
|
||||
## Adding or updating a translation
|
||||
|
||||
## Recommended usage
|
||||
1. Copy the English page to the locale mirror (same relative path under
|
||||
`docs/guide/<lang>/`).
|
||||
2. Translate the body, and the `title` / `description` frontmatter.
|
||||
3. Commit it to the repo.
|
||||
4. Deploy via the cms jail (`npm run deploy`).
|
||||
|
||||
Use this section when you need to:
|
||||
See [How the pipeline works](./how-it-works/) and
|
||||
[Setup instructions](./setup/) for the details.
|
||||
|
||||
- understand where translations belong in git
|
||||
- push source strings to Crowdin
|
||||
- pull translated content back into the repo
|
||||
- troubleshoot localization-specific build issues
|
||||
## Future plan: Crowdin
|
||||
|
||||
Hand-editing locale markdown is fine while the translated surface is small. When
|
||||
translation volume outgrows that, **Crowdin** can be reintroduced to manage
|
||||
translation strings — pushing English source up and pulling completed
|
||||
translations back into the same `docs/guide/<lang>/` layout, with no change to
|
||||
how Astro builds or deploys. Crowdin is **not wired up today**; it is a future
|
||||
scaling option, not a current dependency.
|
||||
|
||||
## Pages in this section
|
||||
|
||||
|
|
|
|||
|
|
@ -1,85 +1,49 @@
|
|||
---
|
||||
title: Setup Instructions
|
||||
description: Set up Crowdin access and use the current cms-jail Astro workflow for localized docs.
|
||||
description: Add a locale and deploy localized docs through the cms-jail Astro workflow.
|
||||
---
|
||||
|
||||
# Setup Instructions
|
||||
|
||||
This page covers the current localization setup path.
|
||||
This page covers adding and shipping a translated locale with the
|
||||
Astro/Starlight-native flow. No translation service or API token is required.
|
||||
|
||||
## What you need
|
||||
|
||||
- the Clawdie repo checked out on the host
|
||||
- a Crowdin API token
|
||||
- a working cms jail with the Astro docs project already provisioned
|
||||
|
||||
The docs runtime is not set up as a separate standalone Astro install anymore.
|
||||
The docs runtime is not a separate standalone Astro install — it is the shared
|
||||
cms-jail docs project.
|
||||
|
||||
## Step 1: Configure Crowdin access
|
||||
## Step 1: Create the locale directory
|
||||
|
||||
You can provide the token in any one of these ways.
|
||||
|
||||
### Option A: token file
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/clawdie
|
||||
echo "tskey-your-token-here" > ~/.config/clawdie/crowdin-token
|
||||
chmod 600 ~/.config/clawdie/crowdin-token
|
||||
```
|
||||
|
||||
### Option B: environment file
|
||||
Locales mirror the English tree under a BCP-47 directory. For Slovenian:
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
echo 'CROWDIN_PERSONAL_TOKEN=tskey-your-token-here' >> .env
|
||||
mkdir -p docs/guide/sl
|
||||
```
|
||||
|
||||
### Option C: shell environment
|
||||
## Step 2: Add a translated page
|
||||
|
||||
Copy the English page to the same relative path under the locale directory,
|
||||
then translate the body and the `title` / `description` frontmatter:
|
||||
|
||||
```bash
|
||||
export CROWDIN_PERSONAL_TOKEN=tskey-your-token-here
|
||||
cp docs/guide/operate/terminal-capture.md \
|
||||
docs/guide/sl/operate/terminal-capture.md
|
||||
# translate docs/guide/sl/operate/terminal-capture.md, then:
|
||||
git add docs/guide/sl/operate/terminal-capture.md
|
||||
git commit -m "docs(sl): translate terminal-capture"
|
||||
```
|
||||
|
||||
## Step 2: Verify Crowdin connectivity
|
||||
Keep the path identical to the English source so Starlight pairs the
|
||||
translation with the right page.
|
||||
|
||||
Run from the host repo root:
|
||||
## Step 3: Deploy localized docs
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
./scripts/crowdin-sync.sh --status
|
||||
```
|
||||
|
||||
If this works, the localization sync scripts can see your token.
|
||||
|
||||
## Step 3: Push source strings
|
||||
|
||||
When English source docs change:
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
./scripts/crowdin-sync.sh --push
|
||||
```
|
||||
|
||||
This publishes source markdown from `docs/public/` to the Crowdin project.
|
||||
|
||||
## Step 4: Pull translations back into the repo
|
||||
|
||||
After translators have updated a locale:
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
./scripts/crowdin-sync.sh --pull
|
||||
```
|
||||
|
||||
This updates translated markdown under paths like:
|
||||
|
||||
- `docs/public/sl/`
|
||||
- `docs/public/de/`
|
||||
- `docs/public/hr/`
|
||||
|
||||
## Step 5: Deploy localized docs
|
||||
|
||||
Deploy still happens through the shared Astro project in the cms jail:
|
||||
Deploy happens through the shared Astro project in the cms jail:
|
||||
|
||||
```bash
|
||||
cd /usr/home/<tenant>/<tenant>-docs
|
||||
|
|
@ -89,22 +53,28 @@ npm run deploy
|
|||
That command:
|
||||
|
||||
1. syncs host-side docs content into the Astro tree
|
||||
2. builds the static site
|
||||
2. builds the static site for every locale present
|
||||
3. deploys it into the cms jail webroot
|
||||
|
||||
## Step 6: Verify
|
||||
## Step 4: Verify
|
||||
|
||||
Check the live site:
|
||||
|
||||
```bash
|
||||
curl -sI https://docs.clawdie.si/
|
||||
curl -sI https://docs.clawdie.si/en/
|
||||
curl -sI https://docs.clawdie.si/sl/
|
||||
```
|
||||
|
||||
Then verify any locale-specific pages you expected to change.
|
||||
Then verify the specific locale pages you expected to change.
|
||||
|
||||
## Notes
|
||||
|
||||
- Edit markdown on the host, not inside the jail.
|
||||
- Crowdin manages translations, not deployment.
|
||||
- Astro deployment is shared with the docs publishing flow, not a separate localization runtime.
|
||||
- A locale only needs the pages you have translated; untranslated pages fall
|
||||
back to the default locale.
|
||||
- Astro deployment is shared with the docs publishing flow, not a separate
|
||||
localization runtime.
|
||||
|
||||
> **Future plan:** Crowdin would slot in here as a string-management layer
|
||||
> (push source / pull translations into `docs/guide/<lang>/`) and would add back
|
||||
> a token-configuration step. It is not used today.
|
||||
|
|
|
|||
|
|
@ -1,62 +1,20 @@
|
|||
---
|
||||
title: Troubleshooting
|
||||
description: Common localization pipeline problems in the current cms-jail Astro workflow.
|
||||
description: Common localized-docs problems in the Astro/Starlight cms-jail workflow.
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## Crowdin token not found
|
||||
|
||||
Typical error:
|
||||
|
||||
```text
|
||||
No API token found
|
||||
```
|
||||
|
||||
Check one of these:
|
||||
|
||||
- `~/.config/clawdie/crowdin-token`
|
||||
- `.env` in the host repo
|
||||
- exported `CROWDIN_PERSONAL_TOKEN`
|
||||
|
||||
Then verify:
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
./scripts/crowdin-sync.sh --status
|
||||
```
|
||||
|
||||
## Push or pull fails against Crowdin
|
||||
|
||||
Check:
|
||||
|
||||
1. the token is valid
|
||||
2. the project still exists in Crowdin
|
||||
3. the target language is enabled there
|
||||
|
||||
Then retry:
|
||||
|
||||
```bash
|
||||
./scripts/crowdin-sync.sh --push
|
||||
./scripts/crowdin-sync.sh --pull
|
||||
```
|
||||
|
||||
## A locale folder is missing after pull
|
||||
|
||||
Check whether translators actually produced content for that locale.
|
||||
|
||||
Expected output paths look like:
|
||||
|
||||
- `docs/public/sl/`
|
||||
- `docs/public/de/`
|
||||
|
||||
If the locale is empty or missing, the issue is usually upstream in Crowdin, not in Astro.
|
||||
|
||||
## Localized page does not appear on the site
|
||||
|
||||
First make sure the translated markdown exists in the repo.
|
||||
First make sure the translated markdown exists in the repo at the mirrored path:
|
||||
|
||||
Then redeploy from the cms jail project:
|
||||
```bash
|
||||
ls docs/guide/sl/operate/terminal-capture.md
|
||||
```
|
||||
|
||||
The locale path must match the English page's relative path exactly. Then
|
||||
redeploy from the cms jail project:
|
||||
|
||||
```bash
|
||||
cd /usr/home/<tenant>/<tenant>-docs
|
||||
|
|
@ -65,32 +23,53 @@ npm run deploy
|
|||
|
||||
If that succeeds, verify the live route with `curl`.
|
||||
|
||||
## A page shows English inside an otherwise translated locale
|
||||
|
||||
That is expected: a locale only overrides the pages you have translated.
|
||||
Untranslated pages fall back to the default (English) locale. Translate and
|
||||
commit the missing page under `docs/guide/<lang>/` to replace the fallback.
|
||||
|
||||
## Locale route 404s
|
||||
|
||||
Check that:
|
||||
|
||||
1. the file exists under `docs/guide/<lang>/` at the right path
|
||||
2. the locale is enabled in the Starlight config of the cms-jail docs project
|
||||
3. you redeployed after adding the file
|
||||
|
||||
## Build fails inside the cms jail
|
||||
|
||||
Use the current runtime path for builds and deploys:
|
||||
Use the runtime path for builds and deploys:
|
||||
|
||||
```bash
|
||||
cd /usr/home/<tenant>/<tenant>-docs
|
||||
npm run build
|
||||
```
|
||||
|
||||
A common cause is malformed frontmatter in a translated file — confirm the
|
||||
`title:` / `description:` keys are intact after translation.
|
||||
|
||||
## Docs deploy works, but translations still look stale
|
||||
|
||||
Check whether the translated markdown was actually pulled into git before deploy:
|
||||
Check whether the translated markdown was actually committed before the deploy:
|
||||
|
||||
```bash
|
||||
cd /home/<agent>/clawdie-ai
|
||||
git diff -- docs/public/sl docs/public/de
|
||||
git diff -- docs/guide/sl docs/guide/de
|
||||
```
|
||||
|
||||
If there are no new locale changes, the deploy is probably working and the content simply was not updated yet.
|
||||
If there are no new locale changes, the deploy is working and the content
|
||||
simply was not updated yet.
|
||||
|
||||
## Tenant sites disappeared after a docs deploy
|
||||
|
||||
That should not happen anymore.
|
||||
|
||||
The current docs deploy path protects:
|
||||
That should not happen. The docs deploy path protects:
|
||||
|
||||
- `/usr/local/www/<tenant>/sites/`
|
||||
|
||||
If tenant-site output was still removed, inspect the deploy script in the Astro project and confirm the protected-path behavior is still present.
|
||||
If tenant-site output was still removed, inspect the deploy script in the Astro
|
||||
project and confirm the protected-path behavior is still present.
|
||||
|
||||
> If a future Crowdin integration is added, pull/sync failures against Crowdin
|
||||
> would be a separate class of problem documented alongside it. Crowdin is not
|
||||
> part of the current flow.
|
||||
|
|
|
|||
108
docs/guide/sl/architecture/control-plane-bridge.md
Normal file
108
docs/guide/sl/architecture/control-plane-bridge.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
title: 'Most krmilne ravnine'
|
||||
description: Dostop do krmilne ravnine Colibri med gostitelji prek omrežja Tailscale.
|
||||
---
|
||||
|
||||
Vsak gostitelj poganja `colibri-daemon`, ki posluša na **lokalni vtičnici Unix**
|
||||
(samo krajevno). Most krmilne ravnine to vtičnico izpostavi kot **vrata [TCP](../reference/okrajsave/#tcp) na
|
||||
vmesniku Tailscale**, da lahko drugi gostitelji v omrežju upravljajo krmilno
|
||||
ravnino — ustvarjajo opravila, registrirajo agente, opazujejo terminale — ne da
|
||||
bi bila vtičnica kdaj dosegljiva z javnega interneta.
|
||||
|
||||
```
|
||||
operater / soležni gostitelj premoščeni gostitelj
|
||||
nc <tailnet-ip> 9190 ──tailscale0──▶ socat TCP-LISTEN:9190
|
||||
│ (bind = naslov tailnet tega gostitelja)
|
||||
▼
|
||||
UNIX-CONNECT /run/colibri/colibri.sock
|
||||
│
|
||||
▼
|
||||
colibri-daemon
|
||||
```
|
||||
|
||||
## Izvedbe
|
||||
|
||||
Most je tanka prednja stran `socat`, ki jo nadzoruje upravitelj storitev
|
||||
gostitelja. Obe strani sta v repozitoriju:
|
||||
|
||||
| Gostitelj | Storitev | Pakiranje |
|
||||
| --------- | -------------------------------- | ----------------------------------------------- |
|
||||
| FreeBSD | rc.d `colibri_bridge` | `packaging/freebsd/colibri_bridge.in` |
|
||||
| Linux | systemd `colibri-bridge.service` | `packaging/linux/` (enota + env + nft + README) |
|
||||
|
||||
Obe v bistvu poganjata:
|
||||
|
||||
```
|
||||
socat TCP-LISTEN:9190,bind=<tailnet-naslov-tega-gostitelja>,fork,reuseaddr \
|
||||
UNIX-CONNECT:/run/colibri/colibri.sock
|
||||
```
|
||||
|
||||
Enota za Linux doda `freebind`, da lahko socat poveže naslov tailnet, še preden
|
||||
ga `tailscaled` do konca vzpostavi, in se tako izogne tekmi pri zagonu.
|
||||
`bind=<tailnet-naslov>` poslušalca obdrži stran od vseh drugih vmesnikov, tudi
|
||||
če se požarni zid pozneje spremeni — to je obramba v globino, ne glavna vrata.
|
||||
|
||||
## Omrežna vrata
|
||||
|
||||
Vrata mostu so odprta **samo na vmesniku Tailscale**, v izvornem požarnem zidu
|
||||
gostitelja:
|
||||
|
||||
- **FreeBSD (pf):** `pass in quick on tailscale0 proto tcp to port 9190 keep state`
|
||||
- **Linux (ufw):** `ufw allow in on tailscale0 to any port 9190 proto tcp`
|
||||
|
||||
Na gostitelju s privzeto zavrnitvijo (npr. ufw) je javna stran že zaprta, zato
|
||||
je potreben le _dovoljujoč_ vnos, vezan na vmesnik. Nabor pravil
|
||||
`packaging/linux/colibri-bridge.nft` je namenjen gostiteljem Linux, ki **ne**
|
||||
poganjajo ufw (privzeto sprejemajoča vhodna veriga); pod ufw je odveč.
|
||||
|
||||
## Varnostni model — meja tailnet je avtorizacija
|
||||
|
||||
Vtičnica krmilne ravnine **nima lastne avtentikacije**. Ko je enkrat
|
||||
premoščena, lahko vsak soležnik, ki gostitelja doseže prek omrežja Tailscale,
|
||||
izda celoten nabor ukazov (`spawn-agent`, `kill-agent`, `intake-task`,
|
||||
`terminal-*`, …). Zato je **meja Tailscale nadzor dostopa**:
|
||||
|
||||
- vrata omejite na poimenovane soležnike s **politiko [ACL](../reference/okrajsave/#acl) v Tailscale** na
|
||||
`:9190`, namesto da bi se zanašali le na pravilo požarnega zidu
|
||||
- vsak premoščeni gostitelj obravnavajte kot tak, ki podeljuje pooblastila
|
||||
krmilne ravnine celotnemu omrežju tailnet, dokler ACL tega ne zoži
|
||||
|
||||
## Opombe glede nastavitve
|
||||
|
||||
- **V gitu ni pravih naslovov tailnet.** Predloge nastavitev prinašajo
|
||||
ograde `TAILSCALE_IP_REQUIRED`; operater ob namestitvi vpiše gostiteljev
|
||||
lastni naslov (`tailscale ip -4`). Privzetki rc.d na FreeBSD se prav tako ne
|
||||
zaženejo, dokler naslov ni nastavljen.
|
||||
- **Skladnost poti vtičnice.** Most se poveže na `/run/colibri/colibri.sock`
|
||||
(FreeBSD: `/var/run/colibri/colibri.sock`); demon mora biti zagnan z ujemajočim
|
||||
`COLIBRI_DAEMON_SOCKET`. Privzeta pot demona je pod `$XDG_DATA_HOME`, do katere
|
||||
zaprta enota systemd (`ProtectHome=yes`) nima dostopa — uporabnikova domača mapa
|
||||
ni vidna. Obe poti usmerite na `/run`.
|
||||
- Uporabnik mostu mora biti v skupini vtičnice demona (vtičnica je `0770`,
|
||||
lastnik + skupina).
|
||||
|
||||
## Preverjanje
|
||||
|
||||
Z drugega gostitelja v omrežju tailnet:
|
||||
|
||||
```sh
|
||||
printf '{"cmd":"status"}\n' | nc -w2 <gostiteljev-tailnet-ip> 9190
|
||||
```
|
||||
|
||||
Zdrav most vrne stanje demona v obliki [JSON](../reference/okrajsave/#json) (vključno z demonovim `host`), kar
|
||||
od konca do konca potrdi dosegljivost prek omrežja.
|
||||
|
||||
## Način Hive — mati in hčere
|
||||
|
||||
Ko dva gostitelja stopita v omrežje Clawdie, se povežeta prek mostov krmilne
|
||||
ravnine in matičnega strežnika. Takrat govorimo v dvojini:
|
||||
|
||||
> **OSA in domedog sta vzpostavila most.** Midva sva registrirala vsak svojega
|
||||
> agenta. Mati naju je prepoznala po profilu strojne opreme in oba sprejela v
|
||||
> hive. Zdaj si deliva opravila — kar en sprejme, drugi prevzame, če prvi nima
|
||||
> pravih zmožnosti.
|
||||
|
||||
V hive načinu matični strežnik (`mother`) samodejno sprejema registracije,
|
||||
razporeja opravila med gostitelje in vodi evidenco o tem, kateri gostitelj je
|
||||
kaj izvedel. Dva gostitelja sta najmanjša hive celica; z vsakim dodatnim
|
||||
gostiteljem se mreža širi, mati pa ostaja ena.
|
||||
44
docs/guide/sl/architecture/index.md
Normal file
44
docs/guide/sl/architecture/index.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Arhitektura
|
||||
description: Postavitev izvajalnega okolja, model izolacije in oblike namestitve.
|
||||
---
|
||||
|
||||
Sistemske reference o tem, kako je Clawdie sestavljen. FreeBSD ostaja referenčna
|
||||
izvedba; Linux naj sledi istim platformnim pogodbam, kjer je podprt.
|
||||
|
||||
## Oblika izvajalnega okolja
|
||||
|
||||
Clawdie teče kot deljena platforma z gostiteljem na prvem mestu:
|
||||
|
||||
- root namestitev ni najemnik nikogar
|
||||
- imenski prostor deljene platforme je `system`
|
||||
- privzeti storitveni račun in identiteta rc.d-storitve ostaneta `clawdie`
|
||||
- `ASSISTANT_NAME` je samo za prikaz
|
||||
- `TENANT_ID` je rezerviran za poznejše dodatne najemnike, kot sta `bob` ali `jane`
|
||||
|
||||
Baze podatkov deljene platforme:
|
||||
|
||||
- `system_ops`
|
||||
- `system_brain`
|
||||
- `system_skills`
|
||||
- `system_git`
|
||||
- `system_web`
|
||||
|
||||
Storitve deljene platforme:
|
||||
|
||||
- storitev Git
|
||||
- spletna storitev
|
||||
- lokalni modeli umetne inteligence
|
||||
|
||||
- [Plastovita pomnilniška tkanina](./layered-memory-fabric/)
|
||||
- [Plastovita duša](./layered-soul/)
|
||||
- [Modeli namestitve](./deployment-models/)
|
||||
- [Model Warden](./warden/)
|
||||
- [Model gostiteljskega operaterja](./host-operator-model/)
|
||||
- [Omrežje ječ](./jail-networking/)
|
||||
- [Izvedba ječ na FreeBSD](./freebsd-jail-implementation/)
|
||||
- [Življenjski cikel Bastille](./bastille/)
|
||||
- [Krmilna ravnina](./controlplane/)
|
||||
- [Most krmilne ravnine](./control-plane-bridge/)
|
||||
- [Colibri](./colibri/)
|
||||
- [Skrbniška plošča](./admin-panel/)
|
||||
37
docs/guide/sl/index.md
Normal file
37
docs/guide/sl/index.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: Pregled
|
||||
description: Operaterska dokumentacija za Clawdie na FreeBSD.
|
||||
---
|
||||
|
||||
Ta stran pokriva operatersko pot za Clawdie na FreeBSD. Osredotoča se na
|
||||
namestitev, postavitev izvajalnega okolja, izolacijo storitev in vsakodnevno
|
||||
upravljanje.
|
||||
|
||||
## Prvi koraki
|
||||
|
||||
- [Pregled namestitve](./install/)
|
||||
- [Namestitev z ISO](./install/iso/)
|
||||
- [Zahteve](./install/requirements/)
|
||||
|
||||
## Upravljanje
|
||||
|
||||
- [Pregled upravljanja](./operate/)
|
||||
- [Varnostni model](./operate/security/)
|
||||
- [Spremljanje](./operate/monitoring/)
|
||||
- [Obnova baze po izpadu](./operate/db-disaster-recovery/)
|
||||
|
||||
## Arhitektura
|
||||
|
||||
- [Pregled arhitekture](./architecture/)
|
||||
- [Modeli namestitve](./architecture/deployment-models/)
|
||||
- [Model Warden](./architecture/warden/)
|
||||
|
||||
## Referenca
|
||||
|
||||
- [Več agentov](./reference/multi-agent/)
|
||||
- [Poglobljeno o SDK](./reference/sdk-deep-dive/)
|
||||
|
||||
## Načrt razvoja
|
||||
|
||||
- [Načrt kanalov](./roadmap/channels-plan/)
|
||||
- [Časovnica kanalov](./roadmap/channels-roadmap/)
|
||||
24
docs/guide/sl/install/controlplane-install.md
Normal file
24
docs/guide/sl/install/controlplane-install.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: 'Namestitev krmilne ravnine'
|
||||
description: Namestite krmilno ravnino Clawdie s standardnim orkestratorjem.
|
||||
---
|
||||
|
||||
Krmilno ravnino namesti standardni orkestrator:
|
||||
|
||||
```bash
|
||||
just install
|
||||
```
|
||||
|
||||
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`.
|
||||
25
docs/guide/sl/install/index.md
Normal file
25
docs/guide/sl/install/index.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Namestitev
|
||||
description: Operaterske poti namestitve za Clawdie, najprej FreeBSD z deljenimi platformnimi pogodbami.
|
||||
---
|
||||
|
||||
Izberite pot, ki ustreza vašemu gostitelju. FreeBSD ostaja referenčna pot
|
||||
namestitve; podpora za Linux naj sledi istim pogodbam za plastovito pomnilniško
|
||||
tkanino, PostgreSQL ter shrambo/izolacijo, namesto da bi postala ločen
|
||||
produktni model. Glejte [Plastovito pomnilniško tkanino](../architecture/layered-memory-fabric/)
|
||||
za cilj deljene podatkovne ravnine.
|
||||
|
||||
## Namestitev z ISO
|
||||
|
||||
To pot uporabite za nov stroj ali ponovno namestitev z zagonskega medija.
|
||||
|
||||
- [Prvi zagon](./first-boot/) — pripravite `setup.txt`, neobvezni `system.env` in zaženite namestitveni program.
|
||||
- [Namestitev z ISO](./iso/) — izberite sliko, zapišite USB in ga zaženite.
|
||||
|
||||
## Namestitev na obstoječem gostitelju
|
||||
|
||||
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.
|
||||
- [Kontrolni seznam za svežo namestitev](./fresh-install-checklist/) — preverite dokončano namestitev.
|
||||
45
docs/guide/sl/install/iso.md
Normal file
45
docs/guide/sl/install/iso.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Namestitev z ISO
|
||||
description: Zagonske slike USB za fizično strojno opremo in namestitve brez povezave.
|
||||
---
|
||||
|
||||
**Repozitorij:** `https://codeberg.org/Clawdie/Clawdie-ISO`
|
||||
**Oznake:** `https://codeberg.org/Clawdie/Clawdie-ISO/tags`
|
||||
|
||||
Ta stran pokriva izbiro slike in zapis na USB. Za nastavitev ob prvem zagonu
|
||||
(`setup.txt`, zahtevane vrstice in kaj pričakovati) glejte
|
||||
[Prvi zagon](../first-boot/).
|
||||
|
||||
## Prenos
|
||||
|
||||
Izberite sliko, ki ustreza vašemu cilju:
|
||||
|
||||
- **Fizična strojna oprema:** namizje + paketi brez povezave za krajevne
|
||||
namestitve
|
||||
- **Oblak:** slika brez zaslona za postavitve v slogu [VPS](../reference/okrajsave/#vps)
|
||||
|
||||
## Zapis na USB
|
||||
|
||||
`/dev/daX` zamenjajte s pravo napravo. Pred zapisom cilj potrdite z
|
||||
`camcontrol devlist` na FreeBSD ali `lsblk` na Linuxu.
|
||||
|
||||
```bash
|
||||
sudo dd if=clawdie-iso-baremetal-DD.mmm.YYYY.img of=/dev/daX bs=1M status=progress
|
||||
```
|
||||
|
||||
Po zapisu lahko bodisi:
|
||||
|
||||
- neposredno uredite nastavitev ob prvem zagonu (`setup.txt`) ali
|
||||
- najprej zaženete neobvezni korak pregleda, da v `system.txt`, `system.env`,
|
||||
`inspect-facts.env` in `suggested-setup.txt` zberete podatke o disku/omrežju
|
||||
- neobvezno pustite, da pregled prazne vrednosti namestitve/shrambe vpiše nazaj
|
||||
v `setup.txt`
|
||||
- neobvezno pustite, da pregled prazna polja strojne opreme vpiše nazaj v
|
||||
`system.env`
|
||||
|
||||
Nato zaženite. Za ostalo glejte [Prvi zagon](../first-boot/).
|
||||
|
||||
## Prilagoditev ali ponovna izgradnja
|
||||
|
||||
Če potrebujete prilagojen nabor paketov ali želite vgraditi določeno različico
|
||||
Clawdie, sledite navodilom za izgradnjo v repozitoriju Clawdie-ISO.
|
||||
68
docs/guide/sl/install/requirements.md
Normal file
68
docs/guide/sl/install/requirements.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: 'Osnovne zahteve'
|
||||
description: Zahteve glede gostitelja, izvajalnega okolja in orodjarne za Clawdie.
|
||||
---
|
||||
|
||||
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`.
|
||||
|
||||
## Gostitelj
|
||||
|
||||
- **OS:** FreeBSD 15.x (ječe so edino podprto izvajalno okolje).
|
||||
- **Pravice:** root ali uporabnik s `sudo` in dostopom do ZFS.
|
||||
- **[ZFS](../reference/okrajsave/#zfs):** zahtevan za ječe Bastille. Posnetki se zajamejo ob mejnikih
|
||||
namestitve, če obstaja `zroot/bastille`; sicer se tiho preskočijo.
|
||||
- **Omrežje:** odhodni [HTTPS](../reference/okrajsave/#https) za namestitev paketov, ponudnika [LLM](../reference/okrajsave/#llm) in Telegram.
|
||||
Odhodni [NAT](../reference/okrajsave/#nat) prek [PF](../reference/okrajsave/#pf) nastavi namestitveni program.
|
||||
|
||||
## 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.
|
||||
- **Bastille** za upravljanje ječ.
|
||||
|
||||
## Filozofija izvajalnega okolja
|
||||
|
||||
Clawdie je en sam proces Node.js, ki orkestrira agente v ječah. Oblikovne
|
||||
zaveze, ki določajo, kaj potrebujete:
|
||||
|
||||
- **Varnost prek izolacije na ravni OS.** Agenti tečejo znotraj ječ FreeBSD.
|
||||
Dostop do lupine je varen, ker se izvaja znotraj ječe, ne na gostitelju.
|
||||
Dostop do datotečnega sistema je omejen na izrecno priklopljene poti.
|
||||
- **Dovolj majhno, da se prebere.** Brez mikrostoritev, brez čakalnih vrst
|
||||
sporočil, brez abstrakcijskih plasti. En proces, peščica izvornih datotek.
|
||||
- **Delovanje, prirojeno UI.** Koda predpostavlja, da imate sodelavca UI.
|
||||
Operaterska orodja (nadzorna plošča, spremljanje) so tanka; pomočnik dopolni
|
||||
vrzel s tem, da neposredno odgovarja na vprašanja o dnevnikih, stanju in
|
||||
nastavitvah.
|
||||
- **Prilagajanje = spremembe kode.** Sprožilna beseda in nekaj osnovnih
|
||||
nastavitev živijo v `.env`. Vse drugo: uredite kodo. Koda je dovolj majhna,
|
||||
da je to varno.
|
||||
|
||||
## Stične površine za povezovanje
|
||||
|
||||
- **Telegram** prek Bot [API](../reference/okrajsave/#api) (`grammy`). Glavni vhodno-izhodni kanal.
|
||||
- **PostgreSQL** za baze za delovanje, pomnilnik in vgrajeno znanje. Privzeto je
|
||||
izvajanje na gostitelju (`DB_RUNTIME=host`); nastavite `DB_RUNTIME=jail`, da se
|
||||
namesto tega pripravi namenska ječa db.
|
||||
- **Ponudnik [LLM](../reference/okrajsave/#llm)** po vaši izbiri. OpenRouter je priporočena zagonska pot; po
|
||||
namestitvi preklopite na neposredne ključe ponudnikov (zAI, Anthropic, OpenAI,
|
||||
Gemini) ali na lokalni Ollama, tako da uredite `.env`. Glejte
|
||||
[Preklop ponudnika ob napaki](../operate/provider-fallback/) za vedenje glede
|
||||
zaznave omejitev in preklopa.
|
||||
|
||||
## Model razširitev z veščinami
|
||||
|
||||
Veščine so način, kako operaterji dodajajo zmožnosti brez razvejanja jedra.
|
||||
Pogoste oblike veščin:
|
||||
|
||||
- **Komunikacijski kanali** (`/add-slack`, `/add-discord` itd.) za razširitev
|
||||
onkraj Telegrama.
|
||||
- **Avtomatizacija brskalnika** prek `agent-browser`, ki teče znotraj ječe.
|
||||
- **Načrtovana opravila**, registrirana glede na kontekst posamezne skupine.
|
||||
|
||||
Veščine se namestijo v `data/skills/` in se naložijo ob zagonu.
|
||||
76
docs/guide/sl/localization/index.md
Normal file
76
docs/guide/sl/localization/index.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
---
|
||||
title: Lokalizacija dokumentacije
|
||||
description: Lokalizirana dokumentacija Clawdie po načelu Astro/Starlight, s prevodi v gitu.
|
||||
---
|
||||
|
||||
# Lokalizacija dokumentacije
|
||||
|
||||
Clawdie lokalizira dokumentacijo **izvorno v Astro/Starlight**: vsak jezik je
|
||||
navaden markdown, voden v git repozitoriju, vgrajeno usmerjanje i18n v Starlight
|
||||
pa iz tega zgradi eno statično stran s podstranmi za posamezne jezike. V živi
|
||||
poti ni zunanje prevajalske storitve.
|
||||
|
||||
## Vir resnice
|
||||
|
||||
Vsa dokumentacija — izvirnik in prevodi — živi pod `docs/guide/`:
|
||||
|
||||
- angleščina je **privzeti jezik** in je v korenu drevesa, npr.
|
||||
`docs/guide/operate/terminal-capture.md`
|
||||
- vsak drugi jezik zrcali to strukturo pod imenikom z oznako [BCP](../reference/okrajsave/#bcp)-47, npr.
|
||||
`docs/guide/sl/operate/terminal-capture.md` (slovenščina)
|
||||
|
||||
Repozitorij je uredniški vir resnice za vse jezike.
|
||||
|
||||
```text
|
||||
docs/guide/
|
||||
├── operate/terminal-capture.md # en (privzeto)
|
||||
├── architecture/control-plane-bridge.md
|
||||
└── sl/ # slovensko zrcalo
|
||||
├── operate/terminal-capture.md
|
||||
└── architecture/control-plane-bridge.md
|
||||
```
|
||||
|
||||
## Gradnja in objava
|
||||
|
||||
Deljeni dokumentacijski projekt Astro/Starlight bere `docs/guide/`, uporabi
|
||||
usmerjanje jezikov v Starlight in zgradi statični izhod za vsak jezik. Objava
|
||||
poteka prek ječe cms:
|
||||
|
||||
- vir v repozitoriju: `bootstrap/cms/clawdie-docs/`
|
||||
- pot izvajanja v ječi cms: `/usr/home/<tenant>/<tenant>-docs/`
|
||||
|
||||
```bash
|
||||
cd /usr/home/<tenant>/<tenant>-docs
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
Ta ena sama pot objave zažene sinhronizacijo vsebine in gradnjo Astro za **vse**
|
||||
jezike — lokalizacija nima ločene poti objave, ampak teče po običajni gradnji
|
||||
dokumentacije. Za celoten operaterski potek glejte
|
||||
[Objava dokumentacije in najemniških strani](../operate/docs-publishing/).
|
||||
|
||||
## Dodajanje ali posodabljanje prevoda
|
||||
|
||||
1. Angleško stran kopirajte v jezikovno zrcalo (enaka relativna pot pod
|
||||
`docs/guide/<lang>/`).
|
||||
2. Prevedite besedilo ter polji `title` / `description` v glavi.
|
||||
3. Potrdite spremembo v repozitorij.
|
||||
4. Objavite prek ječe cms (`npm run deploy`).
|
||||
|
||||
Glejte [Kako poteka cevovod](./how-it-works/) in
|
||||
[Navodila za nastavitev](./setup/) za podrobnosti.
|
||||
|
||||
## Prihodnji načrt: Crowdin
|
||||
|
||||
Ročno urejanje jezikovnih datotek je v redu, dokler je prevedena površina
|
||||
majhna. Ko obseg prevajanja to preraste, je mogoče znova vpeljati **Crowdin** za
|
||||
upravljanje prevajalskih nizov — ta bi pošiljal angleški izvirnik in vračal
|
||||
dokončane prevode v isto razporeditev `docs/guide/<lang>/`, brez sprememb v tem,
|
||||
kako Astro gradi in objavlja. Crowdin **danes ni vključen**; je možnost za
|
||||
prihodnjo rast, ne trenutna odvisnost.
|
||||
|
||||
## Strani v tem razdelku
|
||||
|
||||
- [Kako poteka cevovod](./how-it-works/)
|
||||
- [Navodila za nastavitev](./setup/)
|
||||
- [Odpravljanje težav](./troubleshooting/)
|
||||
16
docs/guide/sl/operate/index.md
Normal file
16
docs/guide/sl/operate/index.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
title: Upravljanje
|
||||
description: Priročniki in operativne reference za Clawdie.
|
||||
---
|
||||
|
||||
Priročniki za vsakodnevno upravljanje in obnovo.
|
||||
|
||||
- [Varnost](./security/)
|
||||
- [Spremljanje](./monitoring/)
|
||||
- [Zajem terminala in razvrščanje po prepoznavah](./terminal-capture/)
|
||||
- [Operaterski ukazi](./operator-commands/)
|
||||
- [Strukturirana poročila](./structured-reports/)
|
||||
- [Preklop ponudnika ob napaki](./provider-fallback/)
|
||||
- [Objava dokumentacije in najemniških strani](./docs-publishing/)
|
||||
- [Obnova baze po izpadu](./db-disaster-recovery/)
|
||||
- [Shramba Git](./git-storage/)
|
||||
82
docs/guide/sl/operate/terminal-capture.md
Normal file
82
docs/guide/sl/operate/terminal-capture.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
title: 'Zajem terminala in razvrščanje po prepoznavah'
|
||||
description: Razdvojena zgodovina podoken tmux z opozorili na napake ob prehodu.
|
||||
---
|
||||
|
||||
Zajem terminala je tista polovica Glasspana, ki bere zaslon. Medtem ko preostali
|
||||
del Glasspana stanje agenta izpeljuje iz strukturiranih dogodkov [JSONL](../reference/okrajsave/#jsonl), ta plast
|
||||
beleži **dejansko besedilo terminala** v podoknu in ga razvršča glede na znane
|
||||
vzorce — tako si Colibri lahko hkrati _zapomni_, kaj je terminal prikazal, in se
|
||||
_odzove avtomatično_, ko gre kaj prepoznavnega narobe.
|
||||
|
||||
Živi v `colibri-glasspane` (`terminal.rs`, `signatures.rs`), poganja pa jo
|
||||
poizvedovalna zanka `colibri-daemon`.
|
||||
|
||||
## Kako deluje
|
||||
|
||||
- **Naslavljanje po vsebini.** Identiteta okvirja je [`SHA`](../reference/okrajsave/#sha)-256(očiščeno_besedilo)[:12].
|
||||
Enaki zasloni dajo enak id.
|
||||
- **Razdvojena zgodovina.** Snemalnik zavrže vsak okvir, katerega zgostitev je
|
||||
enaka prejšnjemu, zato se poizvedovanje skoraj nespremenljivega podokna vsakih
|
||||
nekaj sekund strni v zgoščen dnevnik _dejanskih_ prehodov stanja, ne v tisoče
|
||||
podvojitev. Zgodovina je omejen krožni medpomnilnik na podokno.
|
||||
- **Razvrščanje po prepoznavah.** Vsak zajeti okvir pregleda `SignatureSet`.
|
||||
Prepoznava nosi resnost (`error`/`warn`/`info`/`ok`), razumljiv predlog
|
||||
ukrepa (`next_action`) in neobvezni `invoke` (veščino za odpravo težave).
|
||||
Zadetki se razvrstijo v `failures` / `warnings` / `info` / `healthy`.
|
||||
- **Opozorila ob prehodu.** Napaka/opozorilo se sporoči le ob okvirju, kjer se
|
||||
_prvič pojavi_ — ne ob vsakem naslednjem okvirju, ki ga še prikazuje. Ko se
|
||||
stanje počisti in pozneje spet pojavi, se sproži znova. To prepreči, da bi
|
||||
vztrajna napaka zasula opozorila.
|
||||
|
||||
Nabor prepoznav je nastavitev za posamezni OS: `SignatureSet::linux_default()`
|
||||
prinaša majhen, dragocen začetni nabor (odpovedi enot systemd, ubijalec ob
|
||||
pomanjkanju pomnilnika, poln disk, neničelni izhodi Dockerja, posredovanje IP,
|
||||
stanje požarnega zidu). Drugi gostitelji naložijo drugačen nabor; ujemalnik je
|
||||
skupen.
|
||||
|
||||
> Izris PNG zajema **ni** del te plasti — to ostaja veščini `tmux-screenshot` za
|
||||
> človeški ogled. Colibri skrbi za zajem, zgodovino in razvrščanje; besedilo in
|
||||
> prepoznave so diagnostični izdelki.
|
||||
|
||||
## Nastavitev
|
||||
|
||||
Nastavi se v okolju demona (privzeto izklopljeno):
|
||||
|
||||
| Spremenljivka | Namen | Privzeto |
|
||||
| ----------------------------------------- | ---------------------------------------------------- | -------------------------------- |
|
||||
| `COLIBRI_TERMINAL_CAPTURE` | Vklopi poizvedovalno zanko (`1`/`true`/`yes`/`on`) | izklopljeno |
|
||||
| `COLIBRI_TERMINAL_CAPTURE_INTERVAL_SECS` | Sekunde med zajemi posameznega opazovanega podokna | `5` |
|
||||
| `COLIBRI_TERMINAL_WATCH` | Z vejicami ločene tarče tmux za opazovanje ob zagonu | _(brez)_ |
|
||||
| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | Posredovanje opozoril ob prehodu v Telegram | _(nenastavljeno → samo dnevnik)_ |
|
||||
|
||||
Kadar žeton bota in id klepeta nista nastavljena, se opozorila čisto prelevijo v
|
||||
vrstico dnevnika demona — funkcijo je varno pustiti vklopljeno tudi brez
|
||||
nastavljenega Telegrama.
|
||||
|
||||
## Ukazi krmilne ravnine
|
||||
|
||||
Prek vtičnice Colibri (JSON, ločen z novimi vrsticami):
|
||||
|
||||
| Ukaz | Učinek |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
|
||||
| `{"cmd":"terminal-watch","target":"clawdie:0"}` | Začni snemati tarčo tmux (seja / `session:window` / `%pane`) |
|
||||
| `{"cmd":"terminal-unwatch","target":"clawdie:0"}` | Nehaj snemati in zavrzi zgodovino podokna |
|
||||
| `{"cmd":"terminal-list"}` | Opazovana podokna s števili okvirjev in trenutno sprožena opozorila |
|
||||
| `{"cmd":"terminal-history","target":"clawdie:0","limit":20}` | Nedavni posneti okvirji (besedilo + prepoznave) za podokno |
|
||||
| `{"cmd":"terminal-poll","target":"clawdie:0"}` | Zajemi takoj namesto čakanja na zanko (`target` neobvezen → vse) |
|
||||
|
||||
`terminal-poll` za vsako podokno vrne, ali je bil okvir `recorded` ali
|
||||
`unchanged` (razdvojen), in morebitna `new_alerts`, ki so se sprožila pri tem
|
||||
zajemu.
|
||||
|
||||
## Opombe za upravljanje
|
||||
|
||||
- Opazujte podokna, ki so pomembna (podokno gradnje, podokno demona, statusno
|
||||
okno), ne vseh — vrednost je v signalu, ne v količini.
|
||||
- Opozorila so sprožena ob prehodu, zato odpovedana storitev opozori enkrat in
|
||||
znova šele po okrevanju in ponovni odpovedi; z `terminal-list` vidite, kaj je
|
||||
trenutno zapahnjeno kot sproženo.
|
||||
- Kadar prepoznava napake nosi `invoke`, ta poimenuje veščino za odpravo težave
|
||||
— opozorilo torej pove »kaj se je pokvarilo in kako popraviti«, ne le, da se je
|
||||
»nekaj zgodilo«.
|
||||
8
docs/guide/sl/reference/index.md
Normal file
8
docs/guide/sl/reference/index.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
title: Referenca
|
||||
description: Poglobljene vsebine in referenčna dokumentacija.
|
||||
---
|
||||
|
||||
- [Več agentov](./multi-agent/)
|
||||
- [Poglobljeno o SDK](./sdk-deep-dive/)
|
||||
- [Slovarček okrajšav](./okrajsave/)
|
||||
25
docs/guide/sl/reference/okrajsave.md
Normal file
25
docs/guide/sl/reference/okrajsave.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: 'Slovarček okrajšav'
|
||||
description: Razlaga tehničnih okrajšav in žargona, ki se pojavljajo v dokumentaciji Clawdie.
|
||||
---
|
||||
|
||||
Če naletite na neznano okrajšavo, je verjetno razložena tukaj. Seznam raste
|
||||
sproti — vsaka okrajšava, uporabljena v dokumentaciji, dobi svoj vnos.
|
||||
|
||||
| Okrajšava | Polni izraz | Kaj pomeni |
|
||||
| --------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **ACL** | Access Control List | Seznam pravil, kdo sme dostopati do česa. V Tailscale ACL določa, kateri gostitelji smejo govoriti med sabo. |
|
||||
| **API** | Application Programming Interface | Programski vmesnik — nabor pravil, kako lahko dva programa komunicirata. Primer: Telegram Bot API. |
|
||||
| **BCP** | Best Current Practice | Najboljša trenutna praksa. BCP-47 je standard za jezikovne oznake (npr. `sl` za slovenščino, `en` za angleščino). |
|
||||
| **HTTPS** | Hypertext Transfer Protocol Secure | Varen spletni prenos — šifrirana različica HTTP. Vsa komunikacija z zunanjimi ponudniki teče prek HTTPS. |
|
||||
| **ISO** | — (disk image) | Slika diska — datoteka, ki vsebuje celoten datotečni sistem, pripravljen za zapis na USB ali pogon. Clawdie ISO je zagonska slika FreeBSD. |
|
||||
| **JSON** | JavaScript Object Notation | Lahko berljiv zapis podatkov v obliki `{"ključ": "vrednost"}`. Krmilna ravnina Colibri uporablja JSON za vse ukaze. |
|
||||
| **JSONL** | JSON Lines | Ena vrstica = en JSON zapis. Uporablja se za dnevnike dogodkov — vsak dogodek je svoja vrstica, ni treba brati cele datoteke naenkrat. |
|
||||
| **LLM** | Large Language Model | Veliki jezikovni model — umetna inteligenca, ki razume in tvori besedilo. Primeri: DeepSeek, Claude, GPT. Clawdie uporablja 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. |
|
||||
| **PF** | Packet Filter | Požarni zid operacijskega sistema FreeBSD. Filtrira omrežni promet po pravilih v `/etc/pf.conf`. |
|
||||
| **SHA** | Secure Hash Algorithm | Varen zgoščevalni algoritem — iz poljubnega besedila naredi kratek "prstni odtis" (zgostitev). `SHA-256` pomeni 256-bitni izhod. Glasspane ga uporablja za primerjavo zaslonov. |
|
||||
| **TCP** | Transmission Control Protocol | Protokol za nadzor prenosa — zagotavlja zanesljiv prenos podatkov med gostitelji. Most krmilne ravnine posluša na vratih TCP. |
|
||||
| **UI** | User Interface | Uporabniški vmesnik — kar operater vidi na zaslonu. Glasspane TUI je terminalski vmesnik za nadzor agentov. |
|
||||
| **VPS** | Virtual Private Server | Navidezni zasebni strežnik — najeta navidezna naprava pri ponudniku oblaka. Slika "cloud" je namenjena postavitvam v slogu VPS. |
|
||||
| **ZFS** | 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. |
|
||||
7
docs/guide/sl/roadmap/index.md
Normal file
7
docs/guide/sl/roadmap/index.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Načrt razvoja
|
||||
description: Dokumenti o načrtu kanalov in platforme.
|
||||
---
|
||||
|
||||
- [Načrt kanalov](./channels-plan/)
|
||||
- [Časovnica kanalov](./channels-roadmap/)
|
||||
Loading…
Add table
Reference in a new issue