## Copilot / AI agent instructions — Target Simulator (concise)

This file contains the minimal, repository-specific guidance an AI coding agent needs to be productive.

1) Big picture
- Type: Python desktop app (Tkinter) that simulates radar targets and communicates with hardware/emulators via SFP/TFTP/Serial.
- Major areas:
  - `target_simulator/core/` — simulation, command builders, communicator interfaces (CommunicatorInterface is the contract).
  - `target_simulator/gui/` — Tkinter windows; `MainView` is the app host and coordinates simulation + communicators.
  - `target_simulator/utils/` — `ConfigManager`, logging helpers (`utils/logger.py`), CSV trace helpers.

2) Key workflows & commands (PowerShell)
- Run app (development):
  $env:PYTHONPATH='C:\src\____GitProjects\target_simulator'; python -m target_simulator
- Open REPL with project path:
  $env:PYTHONPATH='C:\src\____GitProjects\target_simulator'; python
- Run tests (coverage task available): use the workspace task labeled "pytest coverage report" or run directly:
  $env:PYTHONPATH='C:\src\____GitProjects\target_simulator'; pytest --cov=target_simulator.core.models --cov-report=term-missing

3) Project-specific patterns & conventions
- Absolute imports are used throughout; `__main__.py` inserts the project root into `sys.path` for convenience.
- Persistence: `ConfigManager` stores general settings in `settings.json` and scenarios in `scenarios.json` (atomic write + rotating backups `.bak1`, `.bak2`).
- Logging: central queue-based logging that forwards to console/file/GUI. Use `setup_basic_logging(app, LOGGING_CONFIG)` and `add_tkinter_handler(widget, LOGGING_CONFIG)`; temporary increases via `temporary_log_level(logger, level)`.
- Simulation: `SimulationEngine` runs as a daemon thread and emits GUI updates via a Queue; do not change update semantics lightly — runtime sends `tgtset` without qualifiers while debug GUI may include qualifiers.
- Communicator contract: implement `CommunicatorInterface` (methods like `connect(config)->bool`, `disconnect()`, `send_commands(list)`, property `is_open`). `SFP` communicator supports deferred connect and an optional `_use_json_protocol` flag (checked by engine).

4) Important implementation details to preserve
- Debug vs runtime sending: the SFP debug window intentionally sends `tgtset` with state qualifiers (Active/Traceable/Restart) while the live `SimulationEngine` uses `tgtset` without qualifiers to avoid changing lifecycle flags. See `gui/sfp_debug_window.py` and `core/command_builder.py` for the builders.
- Scenarios are saved to a separate `scenarios.json`; `ConfigManager` will avoid overwriting it with empty data and performs atomic replace + rotating backups.
- `MainView._setup_communicator` shows how new communicator types are wired (update this method when adding a protocol).

5) Integration points & external artifacts
- Native libs: Tkinter (GUI). No heavy third-party dependencies are required for core features.
- Optional C++ helpers exist in `cpp/` (e.g., `BupTFTP.cpp`) but are not integrated by default.
- Temporary CSV logs and traces live in `Temp/` (filenames configured in `settings.json` `debug` block).

6) Files to inspect for common tasks (quick links)
- App start: `target_simulator/__main__.py`
- Main UI and lifecycle: `target_simulator/gui/main_view.py`
- Simulation loop and sending logic: `target_simulator/core/simulation_engine.py`
- Command builders: `target_simulator/core/command_builder.py`
- Communicators: `target_simulator/core/*.py` (look for `SFP`, `Serial`, `TFTP` implementations)
- Persistence: `target_simulator/utils/config_manager.py` and `settings.json` / `scenarios.json`
- Logging helpers: `target_simulator/utils/logger.py` and `logger_prefs.json`

7) Small examples (copyable snippets)
- Enable module debug at runtime (REPL):
  import logging; logging.getLogger('target_simulator.gui.sfp_debug_window').setLevel(logging.DEBUG)
- Start app (PowerShell):
  $env:PYTHONPATH='C:\src\____GitProjects\target_simulator'; python -m target_simulator

8) When changing behavior
- If you change how commands are formatted (e.g., `build_tgtset_*`), update both the SimulationEngine logic and the SFP debug sender to keep debug vs runtime semantics clear.
- If you add a new persistent key, prefer storing it under `general` in `settings.json` via `ConfigManager.save_general_settings()`.

9) What the agent should *not* do automatically
- Do not change scenario storage semantics (moving scenarios back into `settings.json`), since `ConfigManager` intentionally separates scenarios and performs backups.

10) If more detail is needed
- Ask which area to expand (GUI wiring, communicator API, command builders, or logging). Provide the specific file and a brief goal and the agent will produce patches and tests.

---

If anything here is unclear or you want additional examples (unit tests, small refactors, or a runtime checklist), tell me which sections to expand and I will iterate.