# AI Agent Instructions for VoxVera

This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.

## Core Mandates

1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.

## Localization Protocol

When adding a new language or updating an existing one:
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`.
- **Landing Page**: Directly update the `const locales` object in `site/index.html`.
- **Documentation**: 
    - Master templates live in `docs/templates/`.
    - Localized overrides live in `voxvera/locales/{lang}/docs/`.
    - **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.

## Universal Mirroring

VoxVera propagates through its own flyers.
- Every `voxvera build` generates `voxvera-portable.zip`.
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).

## Verification Checklist

Before finishing a task, ensure you have:
1. Run unit tests: `pytest tests/test_cli.py`.
2. Verified the localization: `voxvera --lang {lang} check`.
3. Rebuilt the documentation: `voxvera build-docs`.
4. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip`.

---

Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.