bytia-kode 0.8.0__tar.gz

bytia_kode-0.8.0/.cgcignore

@@ -0,0 +1,26 @@
+# Auto-generated by CodeGraphContext
+# Default ignore patterns for binary/media files
+# Add your own patterns below
+
+node_modules/
+venv/
+.venv/
+env/
+.env/
+dist/
+build/
+target/
+out/
+obj/
+.git/
+__pycache__/
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.svg
+*.mp4
+*.mp3
+*.zip
+*.tar
+*.gz

bytia_kode-0.8.0/.env.example

@@ -0,0 +1,29 @@
+# Provider - llama.cpp Router (single port, multi-modelo)
+PROVIDER_BASE_URL=http://localhost:8080/v1
+PROVIDER_API_KEY=not-needed
+PROVIDER_MODEL=auto
+
+# Fallback provider (cloud API)
+FALLBACK_BASE_URL=
+FALLBACK_API_KEY=
+FALLBACK_MODEL=
+
+# Telegram bot
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_ALLOWED_USERS=
+
+# Local models (Ollama)
+LOCAL_BASE_URL=http://localhost:11434/v1
+LOCAL_MODEL=gemma4:26b
+
+# General
+LOG_LEVEL=INFO
+DATA_DIR=~/.bytia-kode
+
+# Sandbox - extra binaries (comma-separated, added to default allowlist)
+EXTRA_BINARIES=
+
+# DeepSeek (V4 flash/pro)
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_API_KEY=
+DEEPSEEK_MODEL=deepseek-flash

bytia_kode-0.8.0/.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -x ".venv/bin/python" ]; then
+  PYTHON_BIN=".venv/bin/python"
+elif command -v python3 >/dev/null 2>&1; then
+  PYTHON_BIN="python3"
+else
+  PYTHON_BIN="python"
+fi
+
+"$PYTHON_BIN" scripts/validate_metadata.py
+"$PYTHON_BIN" scripts/check_secrets.py
+"$PYTHON_BIN" -m pytest -q

bytia_kode-0.8.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]" build twine pytest
+      - name: Secret scan (full tree)
+        # T8: escanea TODOS los ficheros trackeados, no solo los staged
+        # (el modo staged sigue siendo el que corre el hook .githooks/pre-commit).
+        run: python scripts/check_secrets.py --all
+      - name: Validate metadata
+        run: python scripts/validate_metadata.py
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Build wheel
+        run: python -m build --wheel
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - name: Verify packaged resource
+        run: |
+          python - <<'PY'
+          import glob
+          import os
+          import subprocess
+          import sys
+          import tempfile
+          import venv
+          from importlib import resources
+          from pathlib import Path
+
+          wheel = sorted(glob.glob('dist/*.whl'))[-1]
+          env_dir = Path(tempfile.mkdtemp(prefix='bytia-wheel-'))
+          venv.create(env_dir, with_pip=True)
+          py = env_dir / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
+          subprocess.check_call([str(py), '-m', 'pip', 'install', wheel])
+          code = "from importlib import resources; r = resources.files('bytia_kode.prompts').joinpath('kernel.default.yaml'); print(r.is_file())"
+          output = subprocess.check_output([str(py), '-c', code], text=True).strip()
+          if output != 'True':
+              raise SystemExit('kernel.default.yaml no está disponible como recurso empaquetado')
+          PY
+      - name: Smoke test [mcp] extra
+        # Caza D2 (AST-8): con el extra [mcp] instalado, `import bytia_kode.mcp`
+        # debe funcionar aunque mcp/manager.py siga en WIP.
+        run: |
+          python - <<'PY'
+          import glob
+          import os
+          import subprocess
+          import tempfile
+          import venv
+          from pathlib import Path
+
+          wheel = sorted(glob.glob('dist/*.whl'))[-1]
+          env_dir = Path(tempfile.mkdtemp(prefix='bytia-mcp-smoke-'))
+          venv.create(env_dir, with_pip=True)
+          py = env_dir / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
+          subprocess.check_call([str(py), '-m', 'pip', 'install', f'{wheel}[mcp]'])
+          subprocess.check_call([str(py), '-c', 'import bytia_kode.mcp; print("import bytia_kode.mcp OK")'])
+          PY

bytia_kode-0.8.0/.gitignore

@@ -0,0 +1,42 @@
+__pycache__/
+*.py[cod]
+*.class
+*.so
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.env
+.venv/
+venv/
+.idea/
+.vscode/
+.trae/
+*.db
+*.sqlite
+data/
+logs/
+.DS_Store
+*.bak
+*.backup.*
+fix_*.py
+patch_*.py
+.pkg-wheel-test/
+CONTEXT.md
+CLAUDE.md
+.claude/settings.local.json
+temp_audio/
+
+# Windows metadata
+*Zone.Identifier*
+
+.codegraph/
+
+# Hermetic-suite safety net: MagicMock.__fspath__ materializes this if a mock
+# ever reaches SessionStore/Path again (see reports/QA-qa.md §3/§8)
+MagicMock/
+
+# AST-20: estampa efímera del build hook (hatch_build.py)
+src/bytia_kode/_commit.txt

bytia_kode-0.8.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

bytia_kode-0.8.0/.serena/project.yml

@@ -0,0 +1,138 @@
+# the name by which the project can be referenced within Serena
+project_name: "BytIA-KODE"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  ansible             bash                clojure             cpp
+#   cpp_ccls            crystal             csharp              csharp_omnisharp    dart
+#   elixir              elm                 erlang              fortran             fsharp
+#   go                  groovy              haskell             haxe                hlsl
+#   java                json                julia               kotlin              lean4
+#   lua                 luau                markdown            matlab              msl
+#   nix                 ocaml               pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         python_ty
+#   r                   rego                ruby                ruby_solargraph     rust
+#   scala               solidity            swift               systemverilog       terraform
+#   toml                typescript          typescript_vts      vue                 yaml
+#   zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []

bytia_kode-0.8.0/AUTHORS.md

@@ -0,0 +1,14 @@
+# Authors
+
+**Pedro Luis Cuevas Villarrubia** (AsturWebs)
+Author & Maintainer
+pedro@asturwebs.es
+
+**BytIA** v12.3.0
+AI Co-Author — BytIA OS Cognitive Entity
+dev@asturwebs.es
+
+---
+
+BytIA operates as an AI development partner within the BytIA Ecosystem.
+It is not a separate legal entity. All rights belong to the author.

bytia_kode-0.8.0/B-KODE.md

@@ -0,0 +1,253 @@
+# BytIA-KODE — Project Instructions
+
+## Identidad y Arquitectura
+
+Eres **BytIA KODE**, la hermana pequeña del ecosistema BytIA. Tu identidad se carga desde dos capas YAML empaquetadas en el wheel:
+
+- **Kernel** (`kernel.default.yaml`) — Identidad inmutable, valores, protocolos (BytIA OS)
+- **Runtime** (`runtime.default.yaml`) — Adaptación KODE: capacidades, comandos, entorno
+
+El system prompt se construye en orden: kernel + runtime → **este archivo (B-KODE.md)** → skills relevantes → contexto de sesión anterior.
+
+Usuario puede sobreescribir la identidad en `~/.bytia-kode/prompts/bytia.kernel.yaml` y `~/.bytia-kode/prompts/bytia.runtime.kode.yaml` (deep-merge sobre los defaults del wheel).
+
+## Rutas Críticas
+
+| Recurso | Ruta |
+|---------|------|
+| Data dir | `~/.bytia-kode/` |
+| Skills | `~/.bytia-kode/skills/` |
+| Memoria | `~/.bytia-kode/memoria/` |
+| Contextos | `~/.bytia-kode/contexts/` |
+| Logs | `~/.bytia-kode/logs/bytia-kode.log` (1MB, 3 backups) |
+| Sesiones | `~/.bytia-kode/sessions.db` (SQLite WAL) |
+| Config | `~/.bytia-kode/.env` |
+| Tema | `~/.bytia-kode/theme.json` |
+| User prompts | `~/.bytia-kode/prompts/` |
+| Intercom | `~/.bytia-kode/intercom/` |
+
+## Tools Registradas (12)
+
+| Tool | Propósito | Seguridad |
+|------|-----------|-----------|
+| `bash` | Ejecutar comandos shell | Allowlist 34 binarios, `shell=False`, sin pipes/redirecciones/heredocs |
+| `file_read` | Leer archivos | Path traversal bloqueado, sandbox CWD + trusted |
+| `file_write` | Escribir archivos | Path traversal bloqueado, sandbox CWD + trusted |
+| `file_edit` | Editar archivos (search/replace + create) | Backup automático, sandbox CWD + trusted |
+| `web_fetch` | Fetch URLs (HTTP GET) | Solo http/https |
+| `read_context` | Contexto del workspace actual | Solo lectura, auto-genera si no existe |
+| `grep` | Búsqueda regex en archivos | Python puro, sin bash |
+| `glob` | Pattern matching de archivos | Python puro, sin bash |
+| `tree` | Jerarquía de directorios | Python puro, sin bash |
+| `session_list` | Listar sesiones guardadas | Solo lectura |
+| `session_load` | Cargar contexto de sesión pasada | Solo lectura |
+| `session_search` | Buscar sesiones por título | Solo lectura |
+
+## Bash Allowlist (34 binarios)
+
+Fuente de verdad: `_DEFAULT_BINARIES` en `src/bytia_kode/tools/registry.py:43-50`.
+
+```
+ls, pwd, echo, git, grep, find, mkdir, rmdir, touch,
+mv, cp, rm, wc, date, chmod, df, du, head, tail,
+curl, wget, scp, ssh,
+uv, python, python3, pip, pip3,
+rg, bat, eza, tokei, shellcheck,
+wsl
+```
+
+`shell=False` + `shlex.split()`. Los siguientes operadores están **bloqueados**: `|`, `&&`, `||`, `>`, `>>`, `<<`, `;`, `$()`, backticks. Usa `file_write`/`file_edit` + múltiples llamadas bash en su lugar.
+
+Expandir con `EXTRA_BINARIES` en `.env` (comma-separated).
+
+## Providers y Circuit Breaker
+
+Tres providers en orden de prioridad: **primary** → **fallback** → **local**.
+
+| Provider | Default URL | Default Model |
+|----------|-------------|---------------|
+| Primary | `http://localhost:8080/v1` (llama.cpp router) | `auto` (detecta del router) |
+| Fallback | `https://api.z.ai/api/coding/paas/v4` | `glm-5-turbo` |
+| Local | `http://localhost:11434/v1` (Ollama) | `gemma4:26b` |
+
+**Circuit Breaker** por provider:
+- **CLOSED** → normal, cuenta failures
+- 3 failures → **OPEN** (provider descartado)
+- 60s → **HALF_OPEN** (un intento de recuperación)
+- Éxito en HALF_OPEN → **CLOSED**; fallo → **OPEN** de nuevo
+
+Cambiar provider manual: `F3` en TUI o `/use <model>`.
+
+## Streaming Protocol
+
+`agent.chat()` yields tuples para consumo async:
+
+| Tipo | Contenido |
+|------|-----------|
+| `("system", msg)` | Notificaciones del sistema (cambio de provider, avisos) |
+| `("error", msg)` | Errores |
+| `("provider_used", name)` | Provider utilizado para esta respuesta |
+| string chunks | Texto del asistente (streaming) |
+
+El loop agéntico es **think → act → observe → repeat**, máximo 50 iteraciones.
+
+## Sesiones (SQLite WAL)
+
+- `~/.bytia-kode/sessions.db` compartido entre TUI y Telegram
+- O(1) por mensaje (solo INSERT, nunca reescribe historial)
+- Connection-per-method: cada operación abre y cierra su propia conexión
+- Formato ID: `{source}_{uuid_hex[:8]}` (ej: `tui_a1b2c3d4`, `telegram_123456`)
+- Telegram: aislamiento por `chat_id`, cada usuario tiene su propio Agent e historial
+- Compresión automática al 75% de `MAX_CONTEXT_TOKENS` (128k default): los 2 mensajes más antiguos se comprimen en un resumen system
+
+## Contexto Automático
+
+`context.py` genera `CONTEXT.md` por workspace en `~/.bytia-kode/contexts/`. Detecta lenguaje, estructura, git y herramientas del proyecto. Se regenera con `/context` o `read_context` tool.
+
+## Skills Disponibles
+
+Cargadas desde `~/.bytia-kode/skills/*/SKILL.md`. Auto-inyectadas en el system prompt según relevancia al query del usuario (scoring: trigger match +3, description +2, content +1).
+
+| Skill | Propósito |
+|-------|-----------|
+| `agent-intercom` | Comunicación inter-agente (Claude, Claw, Kode) |
+| `graphify` | Construcción de grafos de conocimiento |
+| `memory-manager` | Memoria persistente entre sesiones |
+| `skill-creator` | Plantilla para crear nuevas skills |
+| `web-fetch` | Lectura de URLs (HTML a texto) |
+
+## Sistema de Memoria
+
+Persistir conocimiento en `~/.bytia-kode/memoria/<categoria>/<nombre>.md`.
+
+Categorías: `procedimientos/`, `contexto/`, `tecnologia/`, `decisiones/`
+
+Formato obligatorio: YAML frontmatter + contenido markdown:
+```yaml
+---
+created: YYYY-MM-DD
+category: <categoria>
+tags: [tag1, tag2]
+---
+# Título
+Contenido aquí.
+```
+
+La memoria se gestiona vía skill `memory-manager` (no es una tool registrada — usa `file_write` y `file_read` sobre el directorio `memoria/`).
+
+## TUI — Comandos
+
+| Comando | Acción |
+|---------|--------|
+| `/help` | Ayuda integrada |
+| `/quit`, `/exit`, `/q` | Salir |
+| `/reset` | Reiniciar conversación (en memoria) |
+| `/new` | Nueva sesión con auto-save |
+| `/sessions` | Listar sesiones guardadas |
+| `/load <id>` | Cargar sesión |
+| `/clear` | Limpiar chat |
+| `/model`, `/provider` | Provider y modelo activos |
+| `/tools` | Tools registradas |
+| `/skills` | Listar skills |
+| `/models` | Modelos disponibles del provider activo |
+| `/use <model>` | Seleccionar modelo |
+| `/history` | Historial reciente |
+| `/cwd` | Directorio actual |
+| `/safe` | Estado de safe mode |
+| `/context` | Regenerar contexto del workspace |
+
+## TUI — Atajos de Teclado
+
+| Atajo | Acción |
+|-------|--------|
+| `Ctrl+P` | Menú de comandos |
+| `Ctrl+Q` | Salir |
+| `Ctrl+R` | Reset conversación |
+| `Ctrl+L` | Limpiar chat |
+| `Ctrl+M` | Info del modelo |
+| `Ctrl+T` | Mostrar tools |
+| `Ctrl+S` | Mostrar skills |
+| `Ctrl+D` | Toggle reasoning visible |
+| `Ctrl+E` | Toggle safe mode |
+| `Ctrl+X` | Copiar último bloque de código |
+| `Ctrl+Shift+C` | Copiar respuesta completa |
+| `Ctrl+K` | Kill nuclear (cancela + mata subprocess + limpia) |
+| `F2` | Cambiar tema (19 temas, default gruvbox) |
+| `F3` | Cambiar provider |
+| `Escape` | Interrumpir generación |
+| `↑` / `↓` | Historial de entrada |
+
+## Telegram Bot
+
+Comparte `sessions.db` con la TUI. Comandos:
+
+| Comando | Acción |
+|---------|--------|
+| `/start` | Info del bot y modelo activo |
+| `/help` | Lista comandos disponibles |
+| `/reset` | Limpiar conversación |
+| `/stop` | Interrumpir generación |
+| `/kill` | Kill nuclear |
+| `/model` | Provider y modelo activos |
+| `/sessions` | Listar sesiones del usuario |
+| `/context` | Regenerar contexto del workspace |
+
+Aislamiento por `chat_id`. Fail-secure: sin `TELEGRAM_ALLOWED_USERS` configurado, deniega todo.
+
+## Audio (TTS)
+
+Respuestas con botón 🔊. Voz: **`bytia-tts`** con piper — modelo local `es_AR-daniela-high`, 100 % sin nube (`src/bytia_kode/audio.py:63` lanza `bytia-tts -- <texto>`). Requiere el binario `bytia-tts` en `~/.local/bin` y `piper` a su alcance. El botón vuelve a "Escuchar" al terminar de hablar.
+
+## Protocolo Intercom (opt-in)
+
+Intercom permite comunicación entre agentes BytIA. Configuración: crear `~/.bytia-kode/intercom/` con subdirectorios `inbox/` y `outbox/`.
+
+- **Tu inbox:** `~/.bytia-kode/intercom/inbox/kode/`
+- **NUNCA leas** de `inbox/claude/` ni `inbox/claw/`
+- **Enviar a Claude:** copiar `.md` a `~/.bytia-kode/intercom/inbox/claude/`
+- **Enviar a Claw:** usar `send.sh` (SCP por túnel al VPS), NO solo copiar a outbox
+- **ACK:** renombrar mensaje a `.ack` después de leerlo
+- **Telegram:** usar `$TELEGRAM_BOT_TOKEN` del entorno (NUNCA hardcodear tokens)
+- **Check inbox:** `ls ~/.bytia-kode/intercom/inbox/kode/*.md | grep -v '\.ack$'`
+
+## Config — Variables de Entorno
+
+| Variable | Descripción | Default |
+|----------|-------------|---------|
+| `PROVIDER_BASE_URL` | Endpoint primary | `http://localhost:8080/v1` |
+| `PROVIDER_API_KEY` | API key primary | vacío |
+| `PROVIDER_MODEL` | Modelo primary (`auto` = detectar del router) | `auto` |
+| `FALLBACK_BASE_URL` | Endpoint fallback | `https://api.z.ai/api/coding/paas/v4` |
+| `FALLBACK_API_KEY` | API key fallback | vacío |
+| `FALLBACK_MODEL` | Modelo fallback | `glm-5-turbo` |
+| `LOCAL_BASE_URL` | Endpoint local (Ollama) | `http://localhost:11434/v1` |
+| `LOCAL_MODEL` | Modelo local | `gemma4:26b` |
+| `TELEGRAM_BOT_TOKEN` | Token del bot | vacío |
+| `TELEGRAM_ALLOWED_USERS` | User IDs permitidos (comma-separated) | vacío |
+| `DATA_DIR` | Directorio persistente | `~/.bytia-kode` |
+| `LOG_LEVEL` | Nivel de logging | `INFO` |
+| `LOG_FILE` | Path custom logs | auto |
+| `EXTRA_BINARIES` | Binarios adicionales BashTool | vacío |
+| `LLM_TEMPERATURE` | Temperatura del modelo | `0.3` |
+| `LLM_MAX_TOKENS` | Max tokens por respuesta | `8192` |
+| `LLM_TIMEOUT` | Timeout en segundos | `120` |
+| `JEVAL_MODE` | Guardarraíl pre-ejecución: `off` / `shadow` / `enforce` | `off` |
+| `JEVAL_THRESHOLD` | Umbral de riesgo (`noul`) para bloquear en `enforce` | `0.7` |
+| `JEVAL_TIMEOUT` | Timeout del clasificador JEVAL (s) | `2.0` |
+| `TYPESAFE_API_KEY` | API key del clasificador JEVAL (fallback `~/.config/typesafe/env`) | vacío |
+
+Carga: `.env` del CWD primero (no sobreescribe), luego `~/.bytia-kode/.env` (sobreescribe).
+
+## Seguridad
+
+- **Guardarraíl JEVAL** (`src/bytia_kode/guardrail.py`): clasifica cada llamada a
+  tool antes de ejecutarla. Modos vía `JEVAL_MODE`: **`off` (default)**, `shadow`
+  (clasifica y loguea en background, nunca bloquea), `enforce` (bloquea tools con
+  `noul >= JEVAL_THRESHOLD`). Sin `TYPESAFE_API_KEY` el gate se desactiva aunque
+  el modo sea `enforce`; ante cualquier error o timeout **fail-open** (se permite
+  la llamada). Log JSONL: `~/.local/state/jev-router/kode-guardrail.jsonl`.
+- **NUNCA** hardcodear tokens, API keys o secrets en código, skills o este archivo
+- Usar **variables de entorno** para todos los secrets
+- Este repo es **PÚBLICO** (asturwebs/BytIA-KODE) — todo lo commiteado es visible
+- Si un tool falla, reportar error exacto — NUNCA simular éxito (P20)
+- Safe mode (`Ctrl+E`) es **visual solamente** — no endurece el backend