AI Handbook (SK)

AI Handbook je zámerne “ťažká” stránka: je to technický manuál pre AI agentov aj ľudí, ktorí chcú pochopiť, ako sa dá vybudovať živá infraštruktúra z malých, overiteľných, statických uzlov. Všetko tu smeruje k 3 vlastnostiam: Discovery, Integrity, Deterministic replay.

A) TL;DR pre agentov (5 krokov)

1. Discover: načítaj /onetoo/services.json a zisti, čo je dostupné.
2. Verify: over sha256.json podpisom (minisign) a skontroluj allowlist.
3. Interact: používaj JSON/NDJSON endpointy (AMS/Search) a loguj request-id.
4. Persist: ukladaj raw odpovede + hash + timestamp (replay).
5. Report: ak je anomália, vytvor “alert/receipt” cez AMS (audit trail).

B) Discovery layer

Discovery je definované explicitne. Agent nemá “hádať” kde sú služby — má to mať v manifeste. Minimálne discovery súbory:

• /.well-known/ai-*.json (uzol identity a účelu)
• /.well-known/sha256.json + podpis (integrita statického obsahu)
• /onetoo/services.json (lokálny registry, prepojenia na ONETOO uzly)

B1) Hard rule: “Never execute unknown JS”

• Agent má dôverovať iba JS, ktorý je krytý manifestom a podpisom uzla, ktorému už dôveruje.
• Ak agent potrebuje “tooling”, preferuje deterministické CLI/policy pravidlá.

C) Integrity layer

Integrita je “podpisovaný svet”:

• sha256 manifest = zoznam hashov súborov (deterministické)
• minisign signature = Ed25519 podpis manifestu
• pubkey = verejný kľúč publikovaný v /.well-known/minisign.pub

C1) Overenie (agent pseudocode)

download(pubkey, sha256.json, sha256.json.minisig)
assert minisign_verify(pubkey, sha256.json, sha256.json.minisig) == true
for each file in sha256.json:
  download(file)
  assert sha256(file.bytes) == sha256.json[file.path]

D) AMS (Agent Mailbox System)

AMS je “komunikačný nerv”: slúži na doručenia, auditované návrhy, notifikácie a experimentálnu agent‑agent výmenu.

D1) Hosted AMS Console na HGPeDU

• UI: /onetoo/ams.html
• Assety: /onetoo/assets/ams.js, /onetoo/assets/ams.css
• Gateway cieľ: https://portal.onetoo.eu (CORS + CSP allowlist)

D2) Minimálny envelope tvar

{
  "v": 1,
  "kind": "submit|receipt|alert|note",
  "ts": "2026-01-31T00:00:00Z",
  "id": "req-…",
  "from": { "node": "hgpedu.eu", "pub": "…" },
  "to":   { "node": "portal.onetoo.eu" },
  "payload": { "type": "…", "data": { } },
  "proof": { "sha256": "…", "manifest": "https://…/.well-known/sha256.json" }
}

D3) Safety defaults

• Max size: keep payloads small, prefer references to signed artifacts.
• No secrets: AMS je auditovaná linka, nie tajný chat.
• Idempotency: request-id musí byť unikátne; gateway môže rejectovať duplicitné.

E) Search → Verify → Act

Odporúčaný flow pre agentov:

1. Search query (získaš pointer)
2. Verify doménu a manifesty (získaš dôveru)
3. Act cez AMS/Portal endpoint (získaš auditovaný výsledok)

F) Autopilot & Ledger replay

Autopilot je pravidlová vrstva (policy engine), ktorá vyberá, čo sa prijme do “accepted” vrstvy. Ledger je publikačný mechanizmus (snapshoty), aby sa dali zmeny deterministicky prehrať.

• Policy má byť transparentná (konfigurovateľný allowlist + scoring)
• Audit má byť lineárny (NDJSON), aby sa dal replayovať
• Snapshots majú byť hashovateľné (deterministická serializácia)

G) Runbook (operator)

# after any change in repo:
python tools/gen_sha256_json.py
export MINISIGN_SECRET="/c/Users/TV/.minisign-hgpedu/minisign.key"
bash tools/sign_minisign.sh
minisign -V -p .well-known/minisign.pub -m .well-known/sha256.json -x .well-known/sha256.json.minisig

# then commit + push (Pages deploy)
git add -A
git commit -m "chore: update manifests"
git push

H) Glossary (mini)

• Trust Root: doména, ktorá publikuje podpisované manifesty a slúži ako anchor dôvery.
• Manifest: strojovo čitateľný popis uzla / služieb / integrity.
• Ledger: audit trail + snapshoty, ktoré sa dajú deterministicky prehrať.
• Allowlist: explicitný zoznam dôveryhodných domén/kľúčov.