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.8 TUI, Strands Agents 1.61.1 with Strands Agents Tools 0.8.9, MCP transports on mcp 2.x 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/.

Test suite

• make test runs the unit tests plus the offline end-to-end layer (tests/e2e/offline, marker e2e_offline): the real Textual app, AgentRuntime and strands.Agent against an in-process SSH/SFTP server with a scripted model, so it needs no keys and runs in CI. It also starts real MCP servers (a scripted stdio server and local HTTP endpoints) to check tool calls, startup diagnostics and process cleanup. make test-e2e runs only that layer.
• make test-e2e-live (tests/e2e/live, marker e2e) runs operator scenarios against the real providers; it requires RUN_E2E=1 plus OPENAI_API_KEY, MISTRAL_API_KEY and/or GEMINI_API_KEY, caps model calls per test and never runs in CI. Its MCP scenarios run the real Firecrawl server and need FIRECRAWL_API_KEY and Node.js (npx).
• make test-mistral keeps the Mistral PoC tests (marker mistral, requires MISTRAL_API_KEY); they are tagged e2e so make test never spends tokens.

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); add make test-e2e-live when touching the TUI, the agent runtime or a provider.
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.