Guía de contribución — Shell Sentinel

Este resumen sintetiza las políticas internas que rigen la colaboración en Shell Sentinel: estructura del proyecto, estándares de documentación y mantenimiento de la experiencia web. Cualquier contribución debe seguir estas pautas para proteger la coherencia del producto.

Principios generales

• Aplicación orientada a terminal con sesiones SSH/SFTP persistentes y un asistente IA conversacional.
• Ecosistema en Python 3.12, TUI con Textual 8.2.7, agentes Strands ≥1.45 y herramientas MCP como Firecrawl.
• Dependencias gestionadas con pyproject.toml y lockfiles pip-tools (make lock, make install).
• El trabajo diario se apoya en make install, make format, make lint, make test y make run.
• CI en GitHub Actions (lint + tests en Python 3.12) en cada pull request vía .github/workflows/ci.yml.

Configuración y contenido

• Toda configuración vive en conf/ (evita hardcodear valores en el código).
• Nuevas cadenas deben añadirse en conf/locales/ y utilizar _("clave") al referenciarlas.
• El manual de usuario debe mantenerse en EN/ES/DE siempre que cambie un flujo.
• Documenta los proveedores personalizados en la guía técnica correspondiente y enlázalos desde la web.

Plugins y extensibilidad

• Los plugins se cargan desde plugins/; cada uno debe registrar comandos, traducciones y documentación local.
• No mezcles la documentación específica de un plugin con los manuales generales.
• Respetar los prompts sistema y evitar duplicar conexiones SSH/SFTP fuera de las tools oficiales.

Política de documentación web

• La web en website/ es parte integral del producto y debe reflejar cada cambio funcional o narrativo.
• Cuando se actualicen manuales, comandos o proveedores, sincroniza el contenido del sitio (secciones, tarjetas, enlaces y traducciones).
• Los manuales en línea usan las páginas HTML de website/manuals/; duplica cambios relevantes desde docs/.

Flujo recomendado

1. Activar entorno virtual (python3.12 -m venv .venv, luego source .venv/bin/activate).
2. Instalar dependencias (make install).
3. Tras cambios: make format, make lint, make test (obligatorio antes de abrir PR).
4. Validar la TUI con make run y la web con make website-serve.

Consulta el portal interno de políticas para mayor detalle. Tras cada contribución, verifica que web, manuales y repositorio permanezcan coherentes.