From b0f14643f53ffe8df897caad28db5f038395c906 Mon Sep 17 00:00:00 2001
From: lachtan <martin.blazik@rsj.com>
Date: Wed, 16 Sep 2026 09:17:28 +0200
Subject: [PATCH] nanobot: 2026-09-16 09:17:27

---
 knowledge/README.md            |  5 ++++
 knowledge/nanobot-internals.md | 52 ++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 knowledge/nanobot-internals.md

diff --git a/knowledge/README.md b/knowledge/README.md
index 378ba84..ec45fed 100644
--- a/knowledge/README.md
+++ b/knowledge/README.md
@@ -5,6 +5,11 @@ chování. Nečtou se každý tah — čti on-demand, když jsou pro dotaz relev
 
 ## Soubory
 
+- **`nanobot-internals.md`** — ověřená fakta z nanobot zdrojáků: volání skillů
+  (`$skill-name` injekt vs `/` command router), breaking change 0.3.0 → 0.3.5
+  v odmítání neznámých slash commandů, skill loading pořadí, session storage
+  migrace, env vars, `/health` 503. Sáhni sem při upgradech nanobotu nebo když
+  přestane fungovat něco co dřív fungovalo.
 - **`models.md`** — fakta a naměřené hodnoty o modelech dostupných téhle instanci:
   nakonfigurované presety (provider, kontext, multimodalita), přímo změřená rychlost a
   latence na Ollama Cloud, profil verbozity, rozdíly ve schopnostech (kódování, tvrdé
diff --git a/knowledge/nanobot-internals.md b/knowledge/nanobot-internals.md
new file mode 100644
index 0000000..faf27d4
--- /dev/null
+++ b/knowledge/nanobot-internals.md
@@ -0,0 +1,52 @@
+# nanobot internals — ověřená fakta ze zdrojáků
+
+Ověřeno proti v0.3.5 (`nanobot/agent/skills.py`, `nanobot/command/router.py`, tag v0.3.5 na GitHubu).
+
+## Volání skillů
+
+- **`$skill-name`** v textu zprávy = explicitní injekt SKILL.md do turnu.
+  - Regex: `(?<![\w$])\$([A-Za-z0-9_-]+)` — `get_explicitly_invoked_skills()` v `skills.py`
+  - Zpráva jde normálně k LLM; SKILL.md (bez frontmatteru) se vloží jako
+    `[Active Skills — instructions for this user turn]` RuntimeContextBlock
+  - Nezávislé na command routeru (nezačíná `/`), funguje přes všechny kanály
+    (Telegram ověřeno 2026-09-16)
+  - CLI App aliases se resolvují taky (`installed_skill_aliases()`)
+- **`/jmeno`** = command router. Jen builtins (`/new`, `/stop`, `/model`, `/skill`,
+  `/trigger`, `/pairing`, … — seznam v `nanobot/command/builtin.py`,
+  `BUILTIN_COMMAND_SPECS`). Custom skilly nelze registrovat jako slash command.
+- **v0.3.0 vs v0.3.5 breaking change**: v 0.3.0 `is_dispatchable_command()`
+  neznámý `/cokoli` propustil k LLM (fallback interpretace). V 0.3.5 vrací
+  `True` pro jakýkoliv text začínající `/` → router odmítne
+  (`Unknown command "/usage". Use "/help"...`), zpráva nikdy nedosáhne LLM.
+  Proto custom `/usage` přestalo fungovat po upgradu; `$usage` funguje dál.
+
+## Skill loading pořadí
+
+1. workspace (`workspace/skills/`) — highest priority
+2. Agent Plugin skills (`workspace/plugins/`)
+3. builtin (`nanobot/skills/`) — duplicity skipnuté dle jména
+
+Disabled skilly se filtrují přes `disabled_skills` + aliases.
+
+## Progresivní loading
+
+System prompt obsahuje jen summary (jméno + description + cesta) —
+`build_skills_summary()`. Plný obsah SKILL.md se načte až:
+- explicitně: `$skill-name` v turnu
+- agent sám: `read_file` na cestu ze summary
+
+## Sessions storage (v0.3.5)
+
+- JSONL soubory: `<config-dir>/sessions/<workspace-id>/` (mimo workspace)
+- Migrace z `<workspace>/sessions/` proběhne automaticky při prvním startu po
+  upgradu (atomic copy, symlinks rejected)
+- Downgrade: `nanobot sessions restore-workspace --config <config.json> --workspace <workspace>`
+
+## Env vars (v0.3.5)
+
+- `NANOBOT_LLM_TIMEOUT_S` — zrušen (Unused)
+- `NANOBOT_STREAM_IDLE_TIMEOUT_S` — default 90 s, idle-based (renewed per stream
+  event), max 3600; platí i pro interní tasky (Dream, heartbeat, title gen)
+- `NANOBOT_MAX_CONCURRENT_REQUESTS` — default unlimited, kladné int = cap
+- `/health` může vracet HTTP 503, když enabled WS channel neběží (Zabbix check!
+  )
\ No newline at end of file