Document backend development guidance

Signed-off-by: Loren Eteval <loren.eteval@proton.me>

Furious/Backends/AGENTS.md

@@ -8,6 +8,18 @@
 - Preserve full user-authored core documents and unknown supported fields. Report a lossless-compatibility failure
   instead of silently compiling or deleting unsupported configuration.
 
+## Structured editor contract
+
+- `factoryToInput()` is normally observational: loading an editor must not add defaults or otherwise mutate the
+  configuration document unless that backend has a documented compatibility normalization, such as Xray transport
+  aliases.
+- `inputToFactory()` writes only fields represented by the editor and returns whether it actually changed the
+  document. Do not materialize an absent effective default merely because the editor displays it.
+- Display unknown future string values exactly and preserve them on an untouched load/save round trip. Editing one
+  known leaf must preserve unknown fields and unknown siblings elsewhere in the same object.
+- A deliberate user switch to a supported tagged variant may replace the incompatible active variant. Keep unrelated
+  extension fields, and do not treat a fallback page used for display as a user selection.
+
 ## Native TUN policy
 
 For a normal connection:

Furious/Backends/ExternalCore/AGENTS.md

@@ -0,0 +1,25 @@
+# External Core backend guidance
+
+## Configuration contract
+
+- External Core is protocol-agnostic. Keep executable path, working directory, argument vector, environment mapping,
+  proxy endpoints, shutdown timeout, and application-tun2socks choice as distinct fields.
+- The editor projects these known fields but must preserve unknown top-level fields. Loading is observational and an
+  untouched save must not normalize paths, arguments, environment variables, or future fields.
+- Execute with `shell=False`. Never concatenate arguments into a shell command or log credentials/environment secrets.
+
+## Runtime and TUN ownership
+
+- Own the exact `Popen` instance and its reader/watcher resources. Startup failure and shutdown must close callbacks,
+  terminate, kill if necessary, and reap the exact child within configured bounds.
+- Application tun2socks is explicit and requires a valid remote address. This backend does not inject a native core TUN
+  block or infer protocol-specific behavior.
+- Validation dialogs are transient asynchronous UI: use the established `open()` ownership path and release them on
+  destruction without retaining them in backend or plugin registries.
+
+## Code review and verification
+
+- Flag shell execution, ambiguous string arguments, inherited transient callbacks, unknown-field loss, and unbounded
+  child-process cleanup.
+- Use fully mocked subprocess and host-network operations. Test mapping round trips, unknown-field preservation,
+  validation failures, output-reader shutdown, tun2socks validation, and repeated editor/dialog destruction.

Furious/Backends/Hysteria1/AGENTS.md

@@ -0,0 +1,22 @@
+# Hysteria1 backend guidance
+
+## Compatibility boundary
+
+- Hysteria1 is an independent legacy backend with its own flat client schema and `hysteria://` share-link behavior.
+  Do not import Hysteria2 nested configuration, obfuscation, or native-TUN assumptions into it.
+- Its structured editor follows the shared observational-load/minimal-write contract. Unknown future string values in
+  combo-backed fields remain visible and survive an untouched round trip.
+- Preserve existing tolerant handling of malformed legacy field types unless a deliberate compatibility migration is
+  part of the task; do not silently rewrite valid user values while loading.
+
+## Runtime and assets
+
+- Runtime setup owns Hysteria1-specific MMDB, geosite, and rule assets. Keep asset preparation and failure cleanup in
+  this backend rather than shared connection managers.
+- Proxy-only tests operate on a copy, set their temporary proxy listener, and must not alter the stored profile.
+
+## Code review and verification
+
+- Flag accidental reuse of Hysteria2 keys, loss of unknown flat fields, or editor factories retained as live widgets.
+- Test URI and mapping compatibility, unknown combo values, runtime document immutability, asset failures, process
+  cleanup, and transient editor destruction.

Furious/Backends/Hysteria2/AGENTS.md

@@ -0,0 +1,29 @@
+# Hysteria2 backend guidance
+
+## Native document and structured editor
+
+- The persisted Hysteria2 client document is the configuration submitted to the embedded core. The compact editor is
+  a partial projection, not a compiler or schema normalizer.
+- Keep upstream field names and values exact. In particular, `realm.ipMode` uses the native values `dual`, `v4`, and
+  `v6`; an absent value has the effective dual-stack default. Unknown future strings remain visible and untouched.
+- Optional nested controls edit only their leaf. Preserve unknown siblings, and do not create optional groups or
+  effective Gecko packet defaults until the user actually changes the represented value.
+- `obfs.type` selects a tagged subtype object. An unknown type must remain visible and preserve its subtype on an
+  untouched round trip. An explicit user switch to a known type may remove the previously active incompatible subtype,
+  while retaining unrelated extension data.
+
+## Runtime, statistics, and TUN
+
+- Runtime materialization passes a derived full Hysteria2 document to `startFromJSON`; do not translate it through an
+  Xray-shaped intermediate representation.
+- With native TUN enabled, replace the runtime `tun` block with the generated block. With it disabled, preserve and
+  recognize a user `tun` block. Download/probe configurations explicitly omit TUN.
+- Keep management/statistics requests bounded and separate from GUI objects. Runtime and worker ownership follows the
+  parent backend and Qt lifetime guidance.
+
+## Code review and verification
+
+- Flag `_modified` shadow state, dynamic combo-item accumulation, fallback pages mistaken for user selections, and
+  nested writes that replace an entire user object.
+- Test known and unknown values, nested sibling preservation, obfs subtype switching, absent-default preservation,
+  native-TUN matrices, proxy-only stripping, and editor destruction.

Furious/Backends/Xray/AGENTS.md

@@ -0,0 +1,27 @@
+# Xray backend guidance
+
+## Documents and editors
+
+- The full Xray JSON document is authoritative. Structured editors project only the selected `proxy` outbound,
+  transport, and TLS fields; preserve every unrelated inbound, outbound, routing field, and extension.
+- Transport and security loading preserves unknown `network` or `security` strings so they remain visible and survive
+  an untouched round trip.
+- `http`, `gun`, and `mkcp` are legacy transport aliases that the editor intentionally normalizes to `h2`, `grpc`, and
+  `kcp` while loading. Keep this compatibility rewrite explicit and covered by tests.
+- Selecting a different known transport or security mode may replace incompatible represented settings. Preserve
+  unknown sibling settings that the selected editor does not own.
+
+## Runtime, routing, and TUN
+
+- Prepare routing, logging, tests, and native TUN only on runtime copies. Keep the selected profile document intact.
+- With Xray native TUN enabled, replace runtime TUN inbounds with the generated inbound. With it disabled, preserve and
+  recognize user TUN inbounds. Proxy-only tests explicitly strip TUN.
+- Xray API statistics, routing assets, and transient asset/routing windows belong to this backend. Keep window owners
+  explicit and never register live editor or dialog instances globally.
+
+## Code review and verification
+
+- Flag editor loading that mutates configuration outside the documented transport-alias normalization or materializes
+  unrelated defaults.
+- Test URI/mapping round trips, unknown transport/security preservation, routing and TUN runtime-copy behavior, asset
+  failure cleanup, and transient editor/window destruction.