build: create a new release version 1.16.0

.fvmrc

@@ -0,0 +1,3 @@
+{
+  "flutter": "3.44.0"
+}

.github/workflows/auto-tag-version.yaml

@@ -0,0 +1,48 @@
+name: auto-tag-version
+
+# After a release PR lands on main, publish the version tag automatically.
+# Reads the app_version field from the root pubspec.yaml and creates an annotated
+# tag X.Y.Z on the merged main commit if it does not already exist.
+# Idempotent: pushes that do not change app_version (or where the tag already
+# exists, e.g. a hotfix X.Y.Z+N reusing the same base) are no-ops.
+# Note: app_version (not the standard version: field) is the release version.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - pubspec.yaml
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create version tag if missing
+        run: |
+          set -euo pipefail
+          # awk (not grep|awk): returns 0 even with no match, so a missing
+          # app_version yields an empty VERSION and reaches the error below
+          # instead of aborting on pipefail.
+          VERSION_FIELD=$(awk '/^app_version:/{print $2; exit}' pubspec.yaml)
+          VERSION="${VERSION_FIELD%%+*}"
+          if [ -z "$VERSION" ]; then
+            echo "::error::Could not read app_version from pubspec.yaml"
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/$VERSION" >/dev/null; then
+            echo "Tag '$VERSION' already exists - nothing to do."
+            exit 0
+          fi
+          echo "Creating tag '$VERSION' on $GITHUB_SHA"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$VERSION" -m "release $VERSION"
+          git push origin "$VERSION"

.github/workflows/callkeep-path-guard.yaml

@@ -0,0 +1,31 @@
+name: callkeep-path-guard
+
+# On develop, webtrit_callkeep must stay a path dependency (see docs/release_versioning.md).
+# This catches a release `git:` ref accidentally back-merged onto develop.
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Uses Ruby's built-in YAML (psych) - always available on GitHub runners, no extra install.
+      - name: Ensure webtrit_callkeep is a path dependency
+        run: |
+          ruby -ryaml -e '
+            dep = (YAML.load_file("pubspec.yaml")["dependencies"] || {})["webtrit_callkeep"]
+            ok = dep.is_a?(Hash) && dep.key?("path") && !dep.key?("git")
+            unless ok
+              warn "::error::On develop, webtrit_callkeep must use a path dependency, not a git ref. A release pin was likely back-merged. See docs/release_versioning.md."
+              exit 1
+            end
+            puts "OK: webtrit_callkeep is a path dependency."
+          '

.github/workflows/callkeep-pin-guard.yaml

@@ -0,0 +1,35 @@
+name: callkeep-pin-guard
+
+# On release branches and release tags, webtrit_callkeep must be pinned to a git ref
+# (see docs/release_versioning.md). Mirror of callkeep-path-guard (which keeps develop on path).
+
+on:
+  push:
+    tags:
+      - "*.*.*"
+  pull_request:
+    branches:
+      - "release/**"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Uses Ruby's built-in YAML (psych) - always available on GitHub runners, no extra install.
+      - name: Ensure webtrit_callkeep is pinned to a git ref
+        run: |
+          ruby -ryaml -e '
+            dep = (YAML.load_file("pubspec.yaml")["dependencies"] || {})["webtrit_callkeep"]
+            git = dep.is_a?(Hash) ? dep["git"] : nil
+            ref = git.is_a?(Hash) ? git["ref"].to_s : ""
+            if ref.empty?
+              warn "::error::On release branches and tags, webtrit_callkeep must be pinned to a git ref (got path/none). See docs/release_versioning.md."
+              exit 1
+            end
+            puts "OK: webtrit_callkeep is pinned to ref #{ref}."
+          '

.github/workflows/git-lint.yml

@@ -33,13 +33,25 @@ jobs:
             exit 1
           fi
 
-          REGEX="^(feat|fix|chore|refactor|test|docs|style|ci|perf|build|revert)(\([^)]+\))?: [^A-Z].+$"
+          # A capitalized first letter in the description is allowed (e.g. "fix: WebRTC ...").
+          REGEX="^(feat|fix|chore|refactor|test|docs|style|ci|perf|build|revert)(\([^)]+\))?: .+$"
+
+          # Legacy commits that predate the current convention and are already merged into
+          # shared history. Rewriting them would rewrite hundreds of commits across dozens of
+          # branches, so they are exempted by exact subject instead.
+          ALLOWLIST=(
+            "fix fix changing info icon color (#836)"
+          )
 
           while IFS= read -r SUBJECT; do
             if [ -z "$SUBJECT" ]; then continue; fi
-
+
+            for ALLOWED in "${ALLOWLIST[@]}"; do
+              if [ "$SUBJECT" = "$ALLOWED" ]; then continue 2; fi
+            done
+
             if [[ ! "$SUBJECT" =~ $REGEX ]]; then
-              echo "Invalid format or capitalized description: '$SUBJECT'"
+              echo "Invalid commit message format: '$SUBJECT'"
               exit 1
             fi
           done <<< "$COMMITS_SUBJECTS"

.gitignore

@@ -59,3 +59,7 @@ makefile.shared
 .claude/settings.local.json
 CLAUDE.local.md
 **/.claude/
+integration_test/patrol_test_bundle.dart
+
+# FVM SDK cache (managed by fvm; version pinned via .fvmrc)
+.fvm/

AGENTS.md

@@ -1,7 +1,12 @@
 # AGENTS.md
 
 WebTrit Phone — Flutter VoIP app, Melos monorepo.
-Flutter 3.32.4 (stable), Android SDK 35.0.1.
+Flutter 3.44.0 (stable), Android SDK 35.0.1.
+
+## Toolchain
+
+- Flutter version is pinned **only** in `.fvmrc` — single source of truth, read by `fvm` locally and by the `webtrit_phone_builder` CI. When you bump it, update the version mentioned above in the same commit. (Older release branches may still carry the legacy `.github/flutter_version.yaml`; the builder falls back to it there.)
+- Use `fvm flutter ...` / `fvm dart ...` so the pinned SDK is used; a bare `flutter` from `PATH` may be a different version. The `.fvm/` SDK cache is gitignored — run `fvm install` once per machine.
 
 ## Build & Test
 
@@ -16,8 +21,8 @@ dart run bin/create_new_schema_dump_and_test_migration.dart   # after Drift tabl
 
 ## Code Standards
 
-- No Cyrillic anywhere (source, comments, strings, logs, keys).
-- No inline comments — DartDoc only for public APIs.
+- No Cyrillic in source, comments, logs, strings, or keys, except translation values in localization ARB files (`lib/l10n/arb/*.arb`).
+- Comments: no redundant *what* comments that restate the code; comments explain non-obvious *why* (rationale, gotchas, workarounds, links to issues). DartDoc for public APIs.
 - No DI frameworks (`get_it`, `injectable`, Service Locator — forbidden).
 - Single quotes; 120-char line width.
 - Never edit `*.g.dart` / `*.freezed.dart` / `*.gr.dart` — regenerate via `build_runner`.
@@ -45,7 +50,26 @@ packages/   → shared libs (must NOT import from lib/)
 
 - State: `@freezed` for state; `sealed class + Equatable` for events (never `freezed` on events).
 - BLoC deps via `Provider`/`RepositoryProvider`; never pass `BuildContext` into BLoC/Service.
+  Exception: localized strings needed inside a callback may close over `context.l10n`, but ONLY
+  when the closure is evaluated lazily (after construction). Do NOT call `context.l10n` synchronously
+  inside `BlocProvider.create` — it uses `dependOnInheritedWidgetOfExactType` which throws
+  "Tried to listen to InheritedWidget in a life-cycle that will never be called again" there.
 - DB: DAOs only — never `AppDatabase` directly; Drift-generated classes stay in repo layer.
 - Theme: never raw `Colors.xxx` or `TextStyle` in widgets; `Theme.of(context).extension<T>()`.
 - Widgets: `StatelessWidget` always (not helper methods); dumb widgets in `features/*/view/widgets/`.
 - Tests: `MockClient`/`mocktail` — no real network calls; DB migrations via `SchemaVerifier`.
+- Routing (`auto_route`): the `AppRouter.routes` tree must ALWAYS be complete — never gate route
+  *declarations* on async/runtime values (server capability, login state, feature flags).
+  `routeCollection` is `late final`, built once at router construction (before server `system-info`
+  loads), so any `if (capability) AutoRoute(...)` is frozen with whatever the value was at startup;
+  later navigation to a route omitted then throws `Failed to navigate to <Route>`. Register every
+  variant unconditionally and decide which one to *show* at navigation/build time (e.g.
+  `AutoTabsRouter.routes`, guards, initial-tab resolver). Sibling routes may share a `path`
+  (`recents`) — `RouteCollection` only requires unique route *names*, and tab matching is name-based.
+
+## Documentation
+
+- `docs/features/features.md` indexes the feature docs; the `docs/` root holds cross-cutting / component and app-level docs.
+- Per feature `<name>` (kebab-case): a small one is a single `docs/features/<name>.md`. Split a grown one into `<name>_ux.md` (product/UX: what the user does, screen states, key widgets, in-progress redesign) + `<name>_arch.md` (code/architecture: bloc, events, state machine, flows, isolates, key patterns), and drop the plain `<name>.md` — `features.md` is the index, keep no redundant per-feature index.
+- Cross-cutting components shared by several features live at the `docs/` root (e.g. `signaling_architecture_target.md`), not under features/; feature docs link to them rather than repeat them. Scenario docs (flows + diagrams) keep a descriptive name and live by scope — cross-component ones at the root (e.g. `incoming_call_scenarios.md`).
+- Each doc: start with a one-line summary + a `Last reviewed:` date; describe current behavior first and put unfinished work under a marked "Redesign / in progress" section; link code by relative path (`lib/features/<name>/...`) and sibling docs relatively; update the doc in the same PR that changes the feature. Plain ASCII (repo convention).

CLAUDE.md

@@ -1,7 +1,7 @@
 # WebTrit Phone — Claude Code
 
 @AGENTS.md
-@docs/call_architecture.md
+@docs/features/call_arch.md
 
 ## Package Docs
 

README.md

@@ -40,48 +40,24 @@ The application offers extensive customization options:
 
 # Testing
 
-## Test commands
-* Run unit and widget tests
+### Unit and widget tests
+* Run unit and widget tests:
   ```bash
   flutter test
   ```
-* Run integration tests in dev mode
-  ```bash
-  patrol develop --dart-define-from-file=../dart_define.json --dart-define-from-file=dart_define.integration_test.json --flavor=deeplinkssmsReceiver
-  ```
-* Build integration tests
-  ```bash
-  patrol build android/ios --dart-define-from-file=../dart_define.json --dart-define-from-file=dart_define.integration_test.json --flavor=deeplinkssmsReceiver
-  ```
-* To specify a test file, use the `-t` option:
-  ```bash
-  patrol build -t patrol_test/call_and_recent_test.dart ...
-  ```
-* For build and deploy to Firebase Test Lab, use the following command from the `tool/scripts` directory:
-  ```bash
-  ./testlab_assemble_android.sh <testfile(optional)>
-  ./testlab_assemble_ios.sh <testfile(optional)>
-  ```
+### Integration tests
+- **Framework**: We use Patrol framework for integration testing.
+It helps us to automate native iOS and Android behaviors and simplifyes routine tasks during testing.
+You can find more information about it here: https://patrol.dev/ 
+Integration tests are located in the `patrol_test` folder.
+
+- **Configuration**: The configuration file `dart_define.integration_test.json` defines all the environment variables (login credentials, contacts, user info, and call settings) for the integration tests. [Integration Test Variables](docs/integration_test_variables.md).
+
+- **Calls test**: For simulating SIP calls during tests, here is [pjsua Companion](packages/pjsua_companion/README.md) — an HTTP server that wraps the `pjsua` CLI to place and answer calls programmatically when app tests is running.
+
+- **Commands**: See [Integration Test Commands](docs/integration_test_commands.md) for all patrol build, run, Firebase Test Lab, and local companion commands.
 
-### Test variables
-
-* `WEBTRIT_APP_TEST_CUSTOM_CORE_URL` (_example core.demo.mycompany.com_)
-* `WEBTRIT_APP_TEST_EMAIL_CREDENTIAL` (_example myaccount@mail.com_)
-* `WEBTRIT_APP_TEST_EMAIL_VERIFY_CREDENTIAL` (_example 123456_)
-* `WEBTRIT_APP_TEST_OTP_CREDENTIAL` (_example +1234566789_)
-* `WEBTRIT_APP_TEST_OTP_VERIFY_CREDENTIAL` (_example 123456_)
-* `WEBTRIT_APP_TEST_PASSWORD_USER_CREDENTIAL`  (_example username_)
-* `WEBTRIT_APP_TEST_PASSWORD_PASSWORD_CREDENTIAL` (_example 123456_)
-* `WEBTRIT_APP_TEST_DEFAULT_LOGIN_METHOD` (_email_ | _password_ | _otp_)
-* `WEBTRIT_APP_TEST_EXT_CONTACT_A` (_example User A_)
-* `WEBTRIT_APP_TEST_EXT_CONTACT_A_NUMBER` (_example 00123_)
-* `WEBTRIT_APP_TEST_EXT_CONTACT_B` (_example User B_)
-* `WEBTRIT_APP_TEST_EXT_CONTACT_B_NUMBER` (_example 00456_)
-* `WEBTRIT_APP_TEST_ACCOUNT_NAME` (_example Test Account_)
-* `WEBTRIT_APP_TEST_ACCOUNT_MAIN_NUMBER` (_example 1230000_)
-* `WEBTRIT_APP_TEST_CALL_NUMBER_A` (_example 1111_)
-* `WEBTRIT_APP_TEST_CALL_NUMBER_B` (_example 2222_)
-* `WEBTRIT_APP_TEST_CROSS_CALL_SLEEP_SECONDS` (_example 10_)
+- **Coverage**: See [Integration Test Coverage](docs/integration_test_coverage.md) for a description of every test file and its steps.
 
 ## Contributing