Contributor handbook — Shell Sentinel

This summary captures the internal policies that govern collaboration on Shell Sentinel: project structure, documentation standards and website maintenance. Every contribution should follow these guidelines to protect product coherence.

General principles

• Terminal-oriented application with persistent SSH/SFTP sessions and a conversational AI assistant.
• Python 3.12 ecosystem, Textual 8.2.7 TUI, Strands Agents ≥1.45 and MCP tools such as Firecrawl.
• Dependencies managed via pyproject.toml and pip-tools lockfiles (make lock, make install).
• Daily work relies on make install, make format, make lint, make test and make run.
• GitHub Actions CI (lint + tests on Python 3.12) runs on every pull request via .github/workflows/ci.yml.

Configuration and content

• All configuration lives in conf/ (avoid hardcoding values in code).
• New strings must be added in conf/locales/ and referenced with _("key").
• User manuals must stay in EN/ES/DE whenever a flow changes.
• Document custom providers in the technical guide and link them from the website.

Plugins and extensibility

• Plugins load from plugins/; each must register commands, translations and local documentation.
• Do not mix plugin-specific documentation with general manuals.
• Respect system prompts and avoid duplicating SSH/SFTP connections outside the official tools.

Website documentation policy

• The site in website/ is part of the product and must reflect every functional or narrative change.
• When manuals, commands or providers change, sync site content (sections, cards, links and translations).
• Online manuals use HTML pages in website/manuals/; mirror relevant changes from docs/.

Recommended workflow

1. Activate virtualenv (python3.12 -m venv .venv, then source .venv/bin/activate).
2. Install dependencies (make install).
3. After changes: make format, make lint, make test (required before opening a PR).
4. Validate the TUI with make run and the website with make website-serve.

Consult the internal policy portal for more detail. After each contribution, verify that the website, manuals and repository remain aligned.