LorenEteval_Furious/AGENTS.md

# Furious repository guidance

## Product and runtime map

- Furious is a cross-platform PySide6 desktop proxy client. Persisted server profiles and subscriptions are interpreted
  by protocol/plugin capabilities, then `ConnectionController` and `ConnectionManager` prepare an attempt-scoped
  configuration and own the selected proxy runtime, optional native or application TUN, system proxy, DNS, and routes.
- `Main.py`, `Furious-GUI.py`, and the installed `Furious` command enter `Furious.__main__`. `AppMainProcess` runs the Qt
  application in an exact child process so the parent can translate crashes and show a fallback report.
  `DesktopApplication` then performs singleton election, composes process-lifetime owners, restores the requested
  connection, runs the event loop, and unwinds acquired stages in reverse order.
- Read the package map as cooperating responsibility layers, not a strict linear stack. `Frozenlib`, `Interface`, and
  `Models` provide foundations and domain values; `Plugins.API` defines extension contracts; bundled backends and
  extensions implement them; repositories persist domain collections; services own workflows/resources; controllers
  own shared state transitions; UI packages adapt those owners; and `Application` composes the process. Compatibility
  wildcard exports and global accessors create some deliberate cross-layer paths, but new work should not widen them.
- Official backends are Xray, Hysteria 1, Hysteria 2, and a structured external-core process. New backend variation
  belongs behind plugin capabilities, not core-name conditionals in shared orchestration.

## 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 exports, plugin contracts, persisted keys, serialized values, IDs, aliases,
  migrations, or semantic exit codes.

## Engineering boundaries

- Make each state authority, resource owner, mutation, commit point, and failure path explicit. Prefer one readable
  canonical path over a compatibility shim plus a second implementation.
- 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, and migrate callers
  incrementally without creating a competing cache.
- Treat persisted configuration as input. Build runtime, routing, probing, logging, TUN, and statistics state from
  explicit copies unless an API is documented as mutating storage. A failed preparatory stage must not change the
  persisted profile; a post-commit side-effect failure must be reported without pretending the commit rolled back.
- Keep platform mutation behind `Frozenlib` and runtime boundaries. Own exact processes, threads, replies, timers, files,
  and handles; cleanup is bounded where responsiveness requires it, idempotent, and never based on process-name searches.
- Internal invariant failures remain visible. Validate user/plugin/network input and return controlled failures with
  useful context at boundaries. Cleanup may continue after one failure, but log the failed owner or stage.
- Treat secrets, subscription payloads, paths, URLs, plugin data, and complete core documents as untrusted. Do not log
  credentials or secret-bearing configurations.

## Generated, curated, and packaged artifacts

- `Furious/Frozenlib/AppResources.py` is generated from `Resources.qrc` and its icon inputs; never hand-edit it. Regenerate
  it with the compatible PySide6 resource compiler after changing the manifest or resources.
- `Furious/Externals/GenTranslation.py` is generator-managed but also retains curated language values and review flags.
  Follow `Furious/Externals/AGENTS.md`; do not treat it as an opaque disposable output.
- `_()` normally receives a static literal. Its only extractable dynamic form is an f-string composed solely of bare
  names from `Furious.Frozenlib.Constants`; ordinary placeholders, attributes, calls, conversions, format specs, and
  `.format()` are not extractable. Curly braces are reserved for constant substitution.
- Keep source execution, wheel/sdist installation, and `Deploy.py`/Nuitka builds viable. Runtime data belongs under
  `Furious/Data`; lazy/plugin/optional imports must remain discoverable without constructing application or UI objects
  at import time. The release workflow builds multiple OS/architecture artifacts, so host-local success is not proof of
  packaged correctness.
- Packaging metadata has overlapping declarations across `pyproject.toml`, `setup.py`, `requirements.txt`, and the
  release workflow. A dependency, Python/Qt floor, entry point, package-data, version, or artifact change must update
  every applicable surface and preserve both standards-based and legacy setuptools builds. `Deploy.py --download` and
  `--cleanup` mutate bundled assets or build trees; run them only when those effects are in scope.
- The release matrix is part of the product boundary: Linux intentionally proves an Essentials-only/no-WebEngine
  fallback, macOS verifies its WebEngine bundle, and Windows verifies native-extension and packaged PE architecture.
  Keep workflow conditions, dependency installation, `Deploy.py` outputs, uploaded patterns, and tag-gated publication
  consistent. Follow `.github/AGENTS.md` for workflow edits.

## 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; source plus packaged checks for
  import/discovery/compiler-sensitive changes.
- 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.

## Keep this guidance useful

- `AGENTS.md` records durable intent, invariants, boundaries, pitfalls, and validation—not a frozen inventory of classes.
  When implementation and guidance diverge, investigate the current code and tests, then update the narrowest applicable
  guide in the same change when the architectural truth has moved.
- Let child guides specialize inherited rules instead of repeating them. Remove obsolete constraints, distinguish a
  compatibility path from the preferred direction, and avoid turning incidental implementation details into permanent
  policy. A new rule should help a future agent make a concrete engineering decision.
- When changing a subsystem, reread the applicable ancestor and child guides as one scope. Amend guidance only for a
  durable discovery: explain the reason, place it at the narrowest useful level, and remove or relax the old rule when
  its protected invariant no longer exists.