docs(agents): document custom profiles, setting changes and the gomobile Core

Author: chen08209

.agents/architecture.md

@@ -17,12 +17,13 @@ dart setup.dart windows
 dart setup.dart android
 ```
 
-The Go core and the Rust helper build automatically: Flutter runs
+The desktop Go core and the Rust helper build automatically: Flutter runs
 `plugins/setup/hook/build.dart` on every `flutter build` and `flutter test`,
 and the hook drives `CoreBuilder` from the `setup_hooks` package in
-`plugins/setup/setup_hooks/`. Android builds take the NDK from the C compiler
-Flutter hands the hook; no `ANDROID_NDK` variable is needed.
-Artifacts land in `libclash/`. The hook reruns only when Go, Rust, or
+`plugins/setup/setup_hooks/`. Artifacts land in `libclash/`. Android's Core is
+the AAR the `:core` Gradle module builds with `gomobile bind` before anything
+compiles against it; that needs `go` on `PATH` and nothing else, since the
+gomobile tools come from `core/go.mod` and the NDK from AGP. The hook reruns only when Go, Rust, or
 `setup_hooks` inputs change; the fingerprint cache lives in
 `.dart_tool/setup_build_cache/`. To force a rebuild, delete that directory:
 
@@ -49,15 +50,16 @@ hooks:
       build_assets: true   # false does the same for the Rust library
 ```
 
-CI flips `setup` to `false` with `yq` before `dart run tool/changelog.dart` and
-`flutter test`, and restores the file afterwards; no test loads the Go core. `rust_api`
-stays on there because the editor tests in `test/plugins/code_forge/` load the Rust
-library the hook builds; the release-notes job, which runs no tests, flips both.
+CI flips `setup` to `false` with `yq` in its throwaway checkout before
+`dart run tool/changelog.dart` and `flutter test`; no test loads the Go core. `rust_api`
+stays on there because the editor tests in `test/plugins/code_forge/` and the socket
+test in `test/core/desktop/ipc_native_test.dart` load the Rust library the hook
+builds; the release-notes job, which runs no tests, flips both.
 Never commit `false`: a build with it set stages whatever `libclash/` already
 holds and bundles no Rust library, which is why `setup.dart` refuses to package
 while it is set. Locally, `false` is worth setting for a Dart-only test loop,
 but the hook cache keys on the user-define, so the first build afterwards runs
-the hooks again. The editor tests still need the Rust library: keep `rust_api`
+the hooks again. The editor and IPC socket tests still need the Rust library: keep `rust_api`
 on, or point `FRB_DART_LOAD_EXTERNAL_LIBRARY_NATIVE_LIB_DIR` at a directory that
 holds a `rust_api` library built from the same sources.
 
@@ -175,7 +177,8 @@ flutter test test/widgets/core_status_button_test.dart
 What those suites own:
 
 - `test/core/desktop/`: replaceable IPC transport, RPC request correlation/failure, direct/Helper process leases, and
-  latest-intent desktop lifecycle convergence.
+  latest-intent desktop lifecycle convergence. `ipc_native_test.dart` runs the transport over a real socket through
+  the Rust `IpcServer`; the server's own behavior is covered by `cargo test` in `plugins/rust_api/rust`.
 - `test/core/service_test.dart`: `CoreService` composition and terminal close behavior.
 - `test/core/protocol_contract_test.dart`: shared Dart/Go method and event-envelope compatibility, including event batches.
 - `test/providers/action_test.dart`: Core start/restart orchestration and overlapping restart requests.
@@ -185,12 +188,13 @@ What those suites own:
 
 ## Native Component Verification
 
-The CI Go-wrapper checks can be reproduced without CGO:
+The CI Go-wrapper checks can be reproduced without CGO, the Android files included:
 
 ```bash
 cd core
 CGO_ENABLED=0 go test .
-CGO_ENABLED=0 go vet .
+CGO_ENABLED=0 go vet . ./cmd/...
+GOOS=android GOARCH=arm64 CGO_ENABLED=0 go vet -tags=with_gvisor . ./mobile ./tun ./platform
 ```
 
 The Windows Helper's loopback/session protocol tests are host-independent by default. Windows CI additionally enables its
@@ -209,6 +213,7 @@ registered with `java_home`, so export it by prefix:
 ```bash
 cd android
 export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"   # elsewhere: any JDK 17
+./gradlew :core:compileDebugKotlin -Ptarget-platform=android-arm64   # builds the gomobile AAR for one ABI
 ./gradlew :service:compileDebugKotlin
 ./gradlew :app:compileDebugKotlin
 ```
@@ -284,7 +289,8 @@ works as is for local previews. `tool/build_site.sh [dir]` assembles it with the
 `gh`. Without `gh` access the page falls back to the newest version in `CHANGELOG.md` and lists the files without sizes.
 It then runs `tool/render_site.mjs` (Node), which writes the English page and a `zh/` copy for search engines: page
 text, the first changelog releases, canonical and `hreflang` links, JSON-LD and `sitemap.xml`, all from the strings,
-changelog parser and release markup in `site/assets/shared.js`. `SITE_URL` overrides the published URL these point at.
+changelog parser and release markup in `site/assets/shared.js`, plus the GitHub star count from `release.json` so the
+nav does not grow when the page loads. `SITE_URL` overrides the published URL these point at.
 On the built site each URL keeps its language: the language button links to the other page and carries the section in
 view, the chosen platform and the changelog search. Only the English root sends readers who chose or prefer Chinese on
 to `zh/`, unless its URL carries `?lang=en`: the button on `zh/` links there with it, so getting back to English never
@@ -311,8 +317,7 @@ In the public repository every branch push runs the `dart` job; in the private
 The `dart` job performs these root-package checks in order:
 
 ```bash
-bash tool/check_commit_msg_test.sh
-bash tool/check_comment_density_test.sh
+bash tool/hooks/test.sh
 flutter pub get
 dart format --output=none --set-exit-if-changed lib test tool plugins setup.dart
 flutter analyze --no-fatal-infos
@@ -321,15 +326,18 @@ flutter test --reporter expanded --coverage
 dart run tool/check_coverage.dart coverage/lcov.info 75
 ```
 
+`tool/hooks/` holds the scripts the git hooks run, and `tool/hooks/test.sh` runs every `*_test.sh` beside them, so a
+new hook script needs only its test file next to it, not a workflow step.
+
 Run `flutter analyze` before committing; CI fails on anything it reports.
 
 Release builds run only for `v*` tag pushes; pull requests trigger nothing.
 Root analysis excludes `plugins/**`, and root tests do not discover nested
 plugin packages, so parallel jobs validate the rest from their own package
 directories: `plugins` (local Flutter packages and the setup build tool), `go`
-(the Core wrapper, plus an NDK-backed vet of the Android files), `android`
-(JVM unit tests for `:common`, `:service` and `:app`, with the Flutter compile
-tasks excluded so no native build hook runs), `rust` (both crates), and a
+(the Core wrapper, plus a vet of the Android files), `android` (JVM unit tests
+for `:common`, `:service` and `:app`, with the Flutter compile tasks excluded
+and the gomobile AAR built for one ABI), `rust` (both crates), and a
 Windows runner for the helper's `windows-service` feature. A `desktop` job also
 compiles a debug build per desktop platform. Release builds run only in the
 public repository and start once every job except `desktop` passes.

.agents/commands.md

@@ -17,7 +17,7 @@ listed in the SDK's `CHANGELOG.md`.
   became the default desktop renderer, Intel (x86_64) Macs flicker across the whole window while scrolling or
   animating, and text can render garbled. Apple Silicon is not affected.
 - **Fix upstream:** landed on `main` before 2026-08-25 and verified on `3.48.0-1.0.pre-404`; it is not in any
-  3.47.x hotfix (checked through 3.47.5).
+  3.47.x hotfix (checked through 3.47.6).
 - **Workaround:** the release job for `macos-15-intel` (`arch: amd64`) runs
   `plutil -replace FLTEnableImpeller -bool NO macos/Runner/Info.plist` before `dart setup.dart`, so only the Intel
   DMG falls back to Skia. The checked-in `Info.plist` does not set the key, so local builds and the arm64 DMG keep

.agents/flutter-upgrade.md

@@ -1,10 +1,10 @@
 # Project Context
 
-FlClash is a multi-platform proxy client based on ClashMeta (mihomo), built with Flutter. It supports Android, Windows, macOS, and Linux, using a Material You design with Surfboard-like UI.
+FlClash is a multi-platform proxy client based on ClashMeta (mihomo), built with Flutter. It supports Android, Windows, macOS, and Linux, using Material You from `material_ui` as the base with Apple's Human Interface interaction conventions layered on top.
 
 ## Version Notes
 
-- Flutter stays on the 3.47.x line. Release CI pins 3.47.4 and is the source
+- Flutter stays on the 3.47.x line. Release CI pins 3.47.6 and is the source
   of truth for release builds; `.fvmrc` and local SDKs may sit on another 3.47
   patch. The editor in `plugins/code_forge` came from `code_forge` 10.14.0, which
   needs Dart 3.13.2, so the CI pin cannot go below Flutter 3.47.2.
@@ -16,11 +16,11 @@ FlClash is a multi-platform proxy client based on ClashMeta (mihomo), built with
 
 ## Forked Dependencies
 
-Two `pubspec.yaml` dependencies are pinned to a fork by commit SHA. Both forks
-live under `chen08209`, the same account that owns this repository, so they are
+One `pubspec.yaml` dependency is pinned to a fork by commit SHA. The fork lives
+under `chen08209`, the same account that owns this repository, so it is
 maintained in-house rather than tracked from a third party: advancing a pin is a
 local decision, and there is no external maintainer to wait on for the patch
-itself. What each fork still waits on is the *upstream* fix that would let the pin
+itself. What the fork still waits on is the *upstream* fix that would let the pin
 be dropped entirely, recorded below.
 
 Each entry records what the fork changes and what has to be true before it can go
@@ -47,13 +47,11 @@ now, see the window plugin section of `architecture.md`.
   directly, and upstream's `^2.0.0` constraint cannot co-resolve with it.
 - Drop the fork when upstream publishes a release that accepts `win32_registry` 3.x.
 
-`yaml_writer` — `chen08209/yaml_writer`, version 2.1.0.
-
-- Adds `StringNode.quoteKey()` and applies it to map keys in `lib/src/node.dart`.
-  Upstream quotes values but emits keys verbatim, so a profile key needing quotes
-  is written as invalid YAML.
-- Drop the fork once upstream quotes map keys by the same
-  `isValidUnquotedString` rule it already applies to values.
+The `yaml_writer` fork (`chen08209/yaml_writer`) was replaced by
+`lib/common/yaml_writer.dart`. Its key quoting let keys such as `!a`, `'a` or
+`0x1F` reach the Core's yaml.v3 as a parse error or a non-string; a merge key
+`<<` stays plain on purpose, because `package:yaml` keeps it as an ordinary key
+and the Core applies the merge.
 
 The `code_forge` fork (`chen08209/code_forge`) is frozen: its Dart code now lives
 in the in-repo `plugins/code_forge` package and its Rust code in the `editor/`
@@ -69,9 +67,15 @@ resolved-until-the-ceiling-moves rather than as debt:
 - `intl` is intentionally unbounded (`any`) and `material_color_utilities` is
   resolved by the Flutter SDK; neither is a bound this repository sets.
 
-`freezed`, the `riverpod` set, `build_runner`, `drift_dev`, `intl_utils` and
-`test` all resolve against the analyzer the pinned SDK ships; none of them is
-held back. When an upgrade fails version solving, record the blocker here with
+The `riverpod` set, `build_runner`, `drift_dev` and `intl_utils` resolve to their
+latest releases. Two are held back:
+
+- `freezed` 4.0.2 needs `analyzer` 14, while `intl_utils` 2.8.16 still requires
+  `analyzer` ^13. It moves once `intl_utils` accepts analyzer 14.
+- `test` 1.32.0 needs `test_api` 0.7.14, and `flutter_test` on Flutter 3.47 pins
+  0.7.12. It moves with the SDK.
+
+When an upgrade fails version solving, record the blocker here with
 what has to change upstream before the pin can move, so the next
 `flutter pub outdated` run does not rediscover it.