Add Fanavaran-only flow-test script and document how to run it.

Track the tester and env template in git so a new tenant can be exercised without a YARA claim; keep filled client env files (secrets, national codes) ignored.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/fanavaran/10-testing.md

@@ -1,5 +1,5 @@
 ---
-last_updated: 2026-08-08
+last_updated: 2026-08-17
 tags: [fanavaran, testing]
 source: fanavaran-module-docs
 ---
@@ -22,6 +22,96 @@ source files/fanavaran-auth/parsian/tokens.env
 # then curl a lookup — see docs/external-api-curls.md
 ```
 
+## Manual Fanavaran flow test (no YARA)
+
+Use this when there is **no YARA claim** and you need to prove a tenant (Parsian / Tejaratno / Moallem) against Fanavaran with the **same stage order as the app**.
+
+Files in git:
+
+| Path | Role |
+|------|------|
+| `scripts/fanavaran-flow-test.sh` | Standalone tester |
+| `scripts/data/fanavaran-flow.env.example` | Template env (section A = you fill, section B = script fills) |
+
+Do **not** commit a filled copy (`fanavaran-flow.moallem.env` and similar). It contains national codes, plate data, and secrets. Copy the example on the machine that runs the test.
+
+### 1. Copy and fill the env
+
+```bash
+cp scripts/data/fanavaran-flow.env.example scripts/data/fanavaran-flow.<client>.env
+```
+
+Fill **section A** before the first run:
+
+- Tenant: `FANAVARAN_CLIENT`, optional auth overrides (`APP_NAME`, `CORP_ID`, `LOCATION`, …)
+- Lookup ids **from that tenant** (`files/fanavaran-lookups/<client>/`): `CLAIM_EXPERT_ID`, `EXPERTISE_CLAIM_EXPERT_ID`, `CLAIM_FILE_TYPE_ID`, `VEHICLE_KIND_ID`, `DMG_SECTION_ID`
+- `INSURANCE_CORP_ID`: Persian caption **or** numeric Fanavaran Id
+- Case data: guilty national code, driver national code + Jalali birthday, plate/chassis/VIN if you have them
+- `ATTACHMENT_FILE`: absolute path(s) to image(s) **on the host that runs the script** (comma-separated for several files)
+- Leave **section B empty** (`POLICY_ID`, `CLAIM_ID`, …)
+
+Lookup ids from Tejaratno/Parsian files are invalid for Moallem (Fanavaran returns `نوع خودرو یافت نشد` and similar). Fetch Moallem lookups first (`GET /lookups/vehicle-kinds` with `FANAVARAN_CLIENT=moallem`, or curl Fanavaran with that tenant’s token).
+
+### 2. Network / IP whitelist
+
+Fanavaran Login is IP-restricted. From a **whitelisted server**, run with no proxy. From **localhost**, Termius dynamic port forwarding does **not** apply automatically — set:
+
+```env
+CURL_PROXY=socks5h://127.0.0.1:<termius-socks-port>
+```
+
+Error `کاربر … مجاز به لاگین با آی پی … نمیباشد` means curl is still using your home IP.
+
+### 3. Run (same sequence as the app)
+
+```text
+auth (cached until Tehran midnight)
+  → policy inquiry → GEN.03 base
+  → driver inquiry + insurance-corp
+  → GEN.12 damage
+  → GEN.07 attachments (one request per file)
+  → GEN.08 expertise
+```
+
+From repo root (`bash`, `curl`, `node`, `awk` required):
+
+```bash
+chmod +x scripts/fanavaran-flow-test.sh
+
+# Full flow (confirms before each POST)
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env
+
+# One or more stages
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages base,damage
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages attachments
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages expertise
+
+# Build payloads / inquiries only
+./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --preview-only
+```
+
+Missing section-A fields can be typed when prompted; they are written back into the env file.
+
+### 4. Token cache (do not Login every run)
+
+`authenticationToken` is stored in `files/fanavaran-auth/<client>/tokens.env` until **Asia/Tehran midnight** (same as Nest). Later runs print `Reusing cached authenticationToken`. Use `--force-login` only when you must mint a new token.
+
+Repeated Login causes Fanavaran `لطفا پس از چند لحظه مجدد تلاش فرمایید`.
+
+### 5. Resume after a stage succeeds
+
+Section B is updated in the **same env file**. Re-run; stages with `CLAIM_ID` / `DMG_CASE_ID` already set are skipped (soft-skip). Payloads and HTTP bodies also land under `files/fanavaran-flow/<client>/<timestamp>/` (gitignored).
+
+### 6. Typical failures
+
+| Message | What to do |
+|---------|------------|
+| Login IP not allowed | Run on the tenant server, or set `CURL_PROXY` to Termius SOCKS |
+| Try again later | Wait; reuse cache; do not `--force-login` |
+| `نوع خودرو یافت نشد` | Set `VEHICLE_KIND_ID` from **this** tenant’s `vehicle-kinds` lookup |
+| File type lookup mismatch | Set `CLAIM_FILE_TYPE_ID` from this tenant’s `file-types` |
+| No `authenticationToken` | Read `login.body.json` in the run folder — Fanavaran `Message` is the real error |
+
 ## Unit / service specs
 
 | Spec | Focus |
@@ -31,7 +121,7 @@ source files/fanavaran-auth/parsian/tokens.env
 
 Prefer mocks for Fanavaran HTTP in unit tests; use live calls only in controlled integration.
 
-## Manual E2E (Parsian template)
+## Manual E2E (Parsian template — via YARA)
 
 1. Create THIRD_PARTY claim with guilty party national code that has an **active** Fanavaran policy.
 2. Confirm history `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED` and `claimId`/`claimNo`.