# Furious repository guidance

## Work from the current tree

- Treat the checked-out tree, including unstaged work, as authoritative. Preserve unrelated changes and do not revive
  deleted experiments from history.
- If `.codegraph/` exists, use it for structural questions before broad searches; use `rg` for exact follow-up.
- Before Python work, inspect `.venv*`/`venv*` at the repository root and prefer its interpreter when usable. Do not
  create or alter an environment without need.
- Keep edits focused. Preserve GPL headers, `from __future__` placement, import grouping, and established naming. Search
  consumers before changing curated package exports, plugin contracts, persisted keys, serialized values, IDs, aliases,
  migrations, or semantic exit codes.

## Design and boundaries

- Make each state authority, resource owner, mutation, and failure path explicit. Prefer one readable canonical path
  over parallel implementations or clever indirection.
- Put policy in its owning layer: models describe data; repositories persist domain collections; `AppSettings` persists
  preferences; services own workflows and temporary resources; controllers own shared state machines; plugins/backends
  own protocol variation; `Application` composes the process; UI adapts those APIs.
- Existing global accessors and live repository collections are compatibility mechanisms, not invitations to add hidden
  ownership. Prefer a narrow injected dependency or named operation for new code when practical.
- Treat persisted configuration as input. Build runtime, routing, testing, logging, TUN, and statistics state from
  explicit copies unless an API is documented as mutating storage.
- Prefer plugin capabilities/factories to protocol conditionals in shared orchestration. Registries may own
  process-lifetime plugins and metadata, never transient UI or active runtimes.
- Keep platform mutation behind `Frozenlib` and runtime boundaries. Own exact processes, threads, replies, timers, and
  handles; cleanup is bounded where responsiveness requires it, idempotent, and never based on process-name searches.

## Errors and external input

- Internal invariant failures remain visible. Validate user/plugin/network input and return a controlled failure with
  useful diagnostics. At OS/network/plugin boundaries, translate expected failures without discarding their cause.
- Cleanup may continue after one failure, but log the failed resource/stage. Narrow best-effort suppression is
  acceptable only when the caller cannot act and the primary outcome remains observable.
- Treat secrets, subscription payloads, paths, URLs, and plugin data as untrusted. Do not log credentials or complete
  secret-bearing configurations.

## Generated and packaged artifacts

- `Furious/Frozenlib/AppResources.py` and `Furious/Externals/GenTranslation.py` are generated. Modify their source inputs
  and run the existing generator; do not hand-edit generated output.
- `_()` normally receives a static literal. Its only dynamic exception is an f-string composed solely of bare names
  from `Furious.Frozenlib.Constants`; ordinary placeholders, attributes, calls, format specs, and `.format()` are not
  extractable. Curly braces are reserved for constant substitution.
- Keep both source execution and `Deploy.py`/Nuitka builds viable. Runtime data belongs under `Furious/Data`; plugin and
  optional imports must remain discoverable without constructing application or UI objects at import time.

## Verification

- Run the narrowest relevant tests, then the affected tier documented in `tests/README.md`. Tests never touch production
  settings, networking, routing, TUN, startup registration, unrelated processes, or external services.
- Format only touched Python files with the repository Black configuration and check those files afterward.
- Match verification to the boundary: round trips/migrations for models and persistence; transitions/signal counts for
  controllers; stale/cancel/cleanup paths for async services; partial startup and bounded cleanup for runtimes; repeated
  destruction for Qt lifetimes; fully mocked host operations for platform helpers.
- Review for duplicated state authorities, persisted-data mutation during preparation, swallowed diagnostics, unowned
  resources, unbounded external-input caches, and shared-manager branches that belong in a capability.