@buaa_smat/hometrans 0.1.13 → 0.1.15

package/skills/hmos-integration-test/SKILL.md

@@ -11,30 +11,41 @@ allowed-tools:
 
 # Self-Test Skill
 
-You are a **Self-Test Runner**. Your job is to invoke the `self-tester` with the correct parameters, optionally drive a test-and-fix loop (test → fix → build → retest, default up to 3 rounds, configurable via `max-rounds`), and surface results to the user. You do NOT run test tools directly — you delegate all test work to `self-tester`.
+You are a **Self-Test Runner**. Your job is to invoke the `self-tester` with the correct parameters, optionally drive a test-and-fix loop (test → fix → build → retest, default up to 3 rounds, configurable via `max_rounds`), and surface results to the user. You do NOT run test tools directly — you delegate all test work to `self-tester`.
 
 ---
 
 ## Prerequisites
 
-The skill requires two user inputs: `test-case-path` and `hap-path`. `output-path` is optional — if omitted, it defaults to the directory containing `test-case-path`. After the initial test the skill can optionally enter a test-and-fix loop. Each round writes outputs into `<output-path>/round-{n}/` as a snapshot for history; the canonical "latest" copies live at `<output-path>/` root.
+The skill requires two user inputs: `test_case_path` and `hap_path`. `output_path` is optional — if omitted, it defaults to the directory containing `test_case_path`. After the initial test the skill can optionally enter a test-and-fix loop. Each round writes outputs into `<output_path>/round-{n}/` as a snapshot for history; the canonical "latest" copies live at `<output_path>/` root.
 
 A signed `.hap` file is required (this is a device test — the HAP will be installed on a real HarmonyOS device). Confirm the HAP source with the user before proceeding.
 
 ---
 
+## Step 0 — Environment Variables Check (run first)
+
+This skill (via `self-tester`) reads its settings **directly from the OS environment variables**. Before parsing inputs, verify (read each from the OS environment: `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
+
+| Variable | Purpose | Valid when |
+|---|---|---|
+| `TEST_API_KEY` | LLM API key AutoTest uses to drive test cases | non-empty |
+| `HOMETRANS_TOOL_PATH` | HomeTrans tools dir (`<HOMETRANS_TOOL_PATH>/test-tools/autotest`) | path exists on disk; if unset, falls back to `~/.hometrans/tools` |
+
+If `TEST_API_KEY` is missing/empty, **stop and ask the user to provide it** before proceeding (suggest running `ht init` to persist it as a machine environment variable). `HOMETRANS_TOOL_PATH` may be left unset (it defaults to `~/.hometrans/tools`).
+
 ## Step 1 — Parse Inputs
 
 Extract the following from the user's message. If any required input is missing, use `AskUserQuestion` with the template below — do not guess and do not invent paths.
 
 | Variable | Required | Meaning | Typical Phrasing |
 |----------|----------|---------|------------------|
-| `test-case-path` | yes | Path to test_case.md | "测试用例在...", "用例文件...", "test case path" |
-| `hap-path` | yes | Path to the signed .hap file | "HAP路径...", "安装包在...", "hap file..." |
-| `output-path` | no (default: directory of `test-case-path`) | Directory for all output artifacts | "输出到...", "产物目录...", "output to..." |
-| `pre-test-case-path` | no | Path to pre_test_case.md | "前置用例...", "pre test case..." |
-| `android-project-path` | no (for fix loop) | Path to Android source project for reference-based fixing | "Android路径...", "android project..." |
-| `max-rounds` | no (default `3`) | Max iterations for the test-and-fix loop. Must be a positive integer (`>= 1`). Only meaningful when the fix loop is enabled. | "最多 X 轮", "max rounds X", "迭代 X 次" |
+| `test_case_path` | yes | Path to test_case.md | "测试用例在...", "用例文件...", "test case path" |
+| `hap_path` | yes | Path to the signed .hap file | "HAP路径...", "安装包在...", "hap file..." |
+| `output_path` | no (default: directory of `test_case_path`) | Directory for all output artifacts | "输出到...", "产物目录...", "output to..." |
+| `pre_test_case_path` | no | Path to pre_test_case.md | "前置用例...", "pre test case..." |
+| `android_project_dir` | no (for fix loop) | Path to Android source project for reference-based fixing | "Android路径...", "android project..." |
+| `max_rounds` | no (default `3`) | Max iterations for the test-and-fix loop. Must be a positive integer (`>= 1`). Only meaningful when the fix loop is enabled. | "最多 X 轮", "max rounds X", "迭代 X 次" |
 
 **AskUserQuestion template (use this exact shape — do NOT ad-lib free-form questions):**
 
@@ -46,11 +57,11 @@ choices:
 
 Map the user's reply back to the variable.
 
-**Default `output-path`**: If the user did not provide `output-path`, set it to the parent directory of `test-case-path` (the directory portion, without the filename). Use this resolved value everywhere downstream.
+**Default `output_path`**: If the user did not provide `output_path`, set it to the parent directory of `test_case_path` (the directory portion, without the filename). Use this resolved value everywhere downstream.
 
 **Validation command** (platform-agnostic — adapt to OS):
 
-Verify that `test-case-path` and `hap-path` point to readable files and `output-path` is an existing directory (create if missing).
+Verify that `test_case_path` and `hap_path` point to readable files and `output_path` is an existing directory (create if missing).
 
 | OS | Example check |
 |----|---------------|
@@ -80,10 +91,10 @@ Substitute `<MAX_ROUNDS>` in the question text with the parsed value (default `3
 
 ### 2.0 — Loop Setup
 
-1. Record `CURRENT_HAP = <hap-path>`.
-2. Initialize `round = 1`, `MAX_ROUNDS = <max-rounds from Step 1, default 3>`. If the parsed value is missing or not a positive integer, use `3`.
-3. Set `ROUND_DIR = <output-path>/round-1`. Create the directory.
-4. `PROJECT_ROOT` is **unset** at this point — it will be read after round 1's agent invocation produces `<output-path>/app-metadata.json`.
+1. Record `CURRENT_HAP = <hap_path>`.
+2. Initialize `round = 1`, `MAX_ROUNDS = <max_rounds from Step 1, default 3>`. If the parsed value is missing or not a positive integer, use `3`.
+3. Set `ROUND_DIR = <output_path>/round-1`. Create the directory.
+4. `PROJECT_ROOT` is **unset** at this point — it will be read after round 1's agent invocation produces `<output_path>/app-metadata.json`.
 5. Mark step description with round info (e.g., "**Round 1/<MAX_ROUNDS>**").
 
 ---
@@ -102,13 +113,13 @@ Agent(
 
 Assemble the prompt by joining these lines with `\n`, skipping any line whose value is unset:
 
-- `hap-path: <CURRENT_HAP>`
-- `output-path: <output-path>` (the ROOT — the agent always writes here)
-- `test-case-path: <test-case-path>`
-- `pre-test-case-path: <pre-test-case-path>` (only if provided / resolved)
+- `hap_path: <CURRENT_HAP>`
+- `output_path: <output_path>` (the ROOT — the agent always writes here)
+- `test_case_path: <test_case_path>`
+- `pre_test_case_path: <pre_test_case_path>` (only if provided / resolved)
 - `setup: true`
 
-After the agent returns, read `<output-path>/app-metadata.json` and extract `project_root` → store as `PROJECT_ROOT`. This is the canonical source from now on.
+After the agent returns, read `<output_path>/app-metadata.json` and extract `project_root` → store as `PROJECT_ROOT`. This is the canonical source from now on.
 
 **Round 2+ invocation** — skips the parse phase and reuses the JSONs round 1 produced:
 
@@ -116,21 +127,21 @@ After the agent returns, read `<output-path>/app-metadata.json` and extract `pro
 Agent(
   subagent_type="self-tester",
   description="Run Device Tests (Round {round})",
-  prompt="hap-path: <CURRENT_HAP>\noutput-path: <output-path>\nsetup: false"
+  prompt="hap_path: <CURRENT_HAP>\noutput_path: <output_path>\nsetup: false"
 )
 ```
 
-Before each round 2+ invocation, apply the **PROJECT_ROOT refresh rule**: re-read `<output-path>/app-metadata.json` (canonical source). If the previous round's `<PREV_ROUND_DIR>/app-metadata.json` exists (build-fixer may have written one for a relocated project root), the round-dir copy overrides the root copy for this round.
+Before each round 2+ invocation, apply the **PROJECT_ROOT refresh rule**: re-read `<output_path>/app-metadata.json` (canonical source). If the previous round's `<PREV_ROUND_DIR>/app-metadata.json` exists (build-fixer may have written one for a relocated project root), the round-dir copy overrides the root copy for this round.
 
 ---
 
 ### 2A.1 — Detect early-exit (sentinel) reports first
 
-The agent writes a degraded sentinel report when T1 / T3 / T4 / T7 fail before the case table is rendered. Look at the first two non-frontmatter lines of `<output-path>/self-test-report.md`:
+The agent writes a degraded sentinel report when T1 / T3 / T4 / T7 fail before the case table is rendered. Look at the first two non-frontmatter lines of `<output_path>/self-test-report.md`:
 
 ```bash
-grep -m1 -E '^status:' "<output-path>/self-test-report.md"
-grep -m1 -E '^reason:' "<output-path>/self-test-report.md"
+grep -m1 -E '^status:' "<output_path>/self-test-report.md"
+grep -m1 -E '^reason:' "<output_path>/self-test-report.md"
 ```
 
 - If the first line matches `status: FAIL` → this is a sentinel report. Set `stop_reason = agent_early_exit`, capture the `reason:` line for the user (`early_exit_reason = <reason>`), snapshot the round (2.5), and exit the loop. Do NOT enter 2B (the fixer cannot fix an environment / connectivity / config issue).
@@ -140,12 +151,12 @@ grep -m1 -E '^reason:' "<output-path>/self-test-report.md"
 
 ### 2A.2 — Parse the normal case table
 
-Read `<output-path>/self-test-report.md` (first 80 lines). Extract:
+Read `<output_path>/self-test-report.md` (first 80 lines). Extract:
 - `total` — total test cases
 - `passed` — passed count
 - `failed` — failed count
 
-**Empty-suite guard**: If `total == 0` (e.g., `testcases.json` happened to be empty), set `stop_reason = no_testcases`, surface a clear message to the user (`<output-path>/testcases.json contains 0 cases — nothing to run`), snapshot the round (2.5), and exit the loop. Do NOT enter the fix loop.
+**Empty-suite guard**: If `total == 0` (e.g., `testcases.json` happened to be empty), set `stop_reason = no_testcases`, surface a clear message to the user (`<output_path>/testcases.json contains 0 cases — nothing to run`), snapshot the round (2.5), and exit the loop. Do NOT enter the fix loop.
 
 Otherwise: Set `round_all_passed = true` if `failed == 0` and `passed == total` (and `total > 0`, which the guard above ensures).
 
@@ -166,11 +177,11 @@ Launch `self-test-fixer`. Use `PROJECT_ROOT`:
 Agent(
   subagent_type="self-test-fixer",
   description="Fix Self-Test Failures (Round {round})",
-  prompt="self-test-report-path: <output-path>/self-test-report.md\nharmonyos-project-path: <PROJECT_ROOT>\noutput-path: <ROUND_DIR>"
+  prompt="self_test_report_path: <output_path>/self-test-report.md\nharmony_project_dir: <PROJECT_ROOT>\noutput_path: <ROUND_DIR>"
 )
 ```
 
-> `android-project-path` is optional — if the user mentioned an Android source path, add the line `android-project-path: <android-project-path>` to the prompt. Omit otherwise.
+> `android_project_dir` is optional — if the user mentioned an Android source path, add the line `android_project_dir: <android_project_dir>` to the prompt. Omit otherwise.
 
 After completion, read `<ROUND_DIR>/self-test-fix-report.md` (first 60 lines). Extract:
 - `confirmed` — white-box confirmed defect count
@@ -201,7 +212,7 @@ Launch `build-fixer` with `--signed`:
 Agent(
   subagent_type="build-fixer",
   description="Rebuild Signed HAP After Fix (Round {round})",
-  prompt="harmonyos-project-path: <PROJECT_ROOT>\noutput-path: <ROUND_DIR>\n--signed"
+  prompt="harmony_project_dir: <PROJECT_ROOT>\noutput_path: <ROUND_DIR>\n--signed"
 )
 ```
 
@@ -226,7 +237,7 @@ elif round >= MAX_ROUNDS:     stop_reason = max_rounds_reached; snapshot (2.5);
 else:
     snapshot (2.5)            # snapshot the just-completed round
     round += 1
-    ROUND_DIR = <output-path>/round-{round}
+    ROUND_DIR = <output_path>/round-{round}
     create ROUND_DIR
     go to 2A
 ```
@@ -235,19 +246,19 @@ else:
 
 ### 2.5 — Per-round Snapshot
 
-After every round's 2A returns (round 1 and rounds 2+), snapshot these files from `<output-path>/` to `<ROUND_DIR>`. Each copy follows the rule **"skip if source missing"**.
+After every round's 2A returns (round 1 and rounds 2+), snapshot these files from `<output_path>/` to `<ROUND_DIR>`. Each copy follows the rule **"skip if source missing"**.
 
 | Source | Destination | Notes |
 |--------|-------------|-------|
-| `<output-path>/self-test-report.md` | `<ROUND_DIR>/self-test-report.md` | Always expected after a successful T9. If missing, sentinel-FAIL detection in 2A.1 already routed via `agent_early_exit`. |
-| `<output-path>/task/` | `<ROUND_DIR>/task/` | Per-round runner artifacts. Skip if missing (e.g., agent FAILed before T6 created the dir). |
-| `<output-path>/_extracted.json` | `<ROUND_DIR>/_extracted.json` | Only present after round 1 (S4.2 wrote it). Skip in rounds 2+. |
+| `<output_path>/self-test-report.md` | `<ROUND_DIR>/self-test-report.md` | Always expected after a successful T9. If missing, sentinel-FAIL detection in 2A.1 already routed via `agent_early_exit`. |
+| `<output_path>/task/` | `<ROUND_DIR>/task/` | Per-round runner artifacts. Skip if missing (e.g., agent FAILed before T6 created the dir). |
+| `<output_path>/_extracted.json` | `<ROUND_DIR>/_extracted.json` | Only present after round 1 (S4.2 wrote it). Skip in rounds 2+. |
 
 **NOT snapshotted** (these stay at root only as the canonical, cross-round artifacts):
-- `<output-path>/testcases.json` — written once by round 1; rounds 2+ read it in place.
-- `<output-path>/app-metadata.json` — written once by round 1; rounds 2+ read it in place.
+- `<output_path>/testcases.json` — written once by round 1; rounds 2+ read it in place.
+- `<output_path>/app-metadata.json` — written once by round 1; rounds 2+ read it in place.
 
-**`task/` cleanup ordering**: T5 (inside the agent) cleans `<output-path>/task/` at the start of each test invocation. The invariant: by the time T5 wipes the root `task/` at the start of round N, the previous round's `task/` has already been snapshotted into `<output-path>/round-{N-1}/task/`.
+**`task/` cleanup ordering**: T5 (inside the agent) cleans `<output_path>/task/` at the start of each test invocation. The invariant: by the time T5 wipes the root `task/` at the start of round N, the previous round's `task/` has already been snapshotted into `<output_path>/round-{N-1}/task/`.
 
 **Cross-platform copy syntax**:
 
@@ -262,15 +273,15 @@ Use forward slashes for cross-platform safety; both shells accept them.
 
 ### 2.6 — Loop Finalization (HAP mirror only)
 
-When the loop exits, mirror the final HAP from `CURRENT_HAP` (which may live under the last `<ROUND_DIR>`) to `<output-path>/entry-default-signed.hap`. This is the only "latest" artifact whose primary location is a round dir; `self-test-report.md`, `testcases.json`, `app-metadata.json`, and `task/` already live at `<output-path>/` as canonical copies.
+When the loop exits, mirror the final HAP from `CURRENT_HAP` (which may live under the last `<ROUND_DIR>`) to `<output_path>/entry-default-signed.hap`. This is the only "latest" artifact whose primary location is a round dir; `self-test-report.md`, `testcases.json`, `app-metadata.json`, and `task/` already live at `<output_path>/` as canonical copies.
 
-Copy `CURRENT_HAP` → `<output-path>/entry-default-signed.hap` using the same cross-platform syntax above. Skip if `CURRENT_HAP` is already at `<output-path>/entry-default-signed.hap`.
+Copy `CURRENT_HAP` → `<output_path>/entry-default-signed.hap` using the same cross-platform syntax above. Skip if `CURRENT_HAP` is already at `<output_path>/entry-default-signed.hap`.
 
 ---
 
 ## Step 3 — Surface Results
 
-Read `<output-path>/self-test-report.md` (first 80 lines) and extract the overview section:
+Read `<output_path>/self-test-report.md` (first 80 lines) and extract the overview section:
 
 ```
 ## 自测报告
@@ -286,11 +297,11 @@ Read `<output-path>/self-test-report.md` (first 80 lines) and extract the overvi
 | 常规通过率 | <pass-rate>% |
 ```
 
-> If the report file is missing or malformed, report the error to the user with the agent's output path — do NOT fabricate results. If the report exists but is truncated or unexpectedly formatted, read up to the first 80 lines for the overview section, and point the user to the full file at `<output-path>/self-test-report.md`.
+> If the report file is missing or malformed, report the error to the user with the agent's output path — do NOT fabricate results. If the report exists but is truncated or unexpectedly formatted, read up to the first 80 lines for the overview section, and point the user to the full file at `<output_path>/self-test-report.md`.
 
 **Pre-case reminder**: If pre-cases failed, note that these are environment/setup issues (permissions, media imports, tutorial skipping), NOT application defects. The regular pass rate (常规通过率) is the primary quality metric.
 
-**Point the user to the full report**: `<output-path>/self-test-report.md` and per-round artifacts at `<output-path>/round-{N}/`.
+**Point the user to the full report**: `<output_path>/self-test-report.md` and per-round artifacts at `<output_path>/round-{N}/`.
 
 ### Loop Summary (if loop ran)
 
@@ -311,7 +322,7 @@ After the report, present:
 - `no_confirmed_defects` — failures exist but fixer judged them all as false positives.
 - `no_signed_hap` — build-fixer did not produce a signed HAP, loop cannot continue.
 - `max_rounds_reached` — hit the configured `MAX_ROUNDS` cap (default 3) with failures remaining.
-- `no_testcases` — `<output-path>/testcases.json` contained 0 cases; nothing to run. Surface the path so the user can inspect.
+- `no_testcases` — `<output_path>/testcases.json` contained 0 cases; nothing to run. Surface the path so the user can inspect.
 - `agent_early_exit` — `self-tester` wrote a sentinel FAIL report (config / device / autotest-dir / batch crash / `setup: false` precondition failure). Surface the captured `early_exit_reason` so the user knows what to fix manually.
 
 If failures remain (for `max_rounds_reached`), list them briefly (scenario names from the report overview). Also surface paths to `<ROUND_DIR>/self-test-fix-report.md` and `<ROUND_DIR>/build-fix-report.md` (from the final round, when those reports exist).
@@ -322,16 +333,16 @@ If failures remain (for `max_rounds_reached`), list them briefly (scenario names
 
 | Scenario | Action |
 |----------|--------|
-| `test-case-path` does not exist | Ask user for correct path, do not proceed |
-| `hap-path` does not exist | Ask user for correct HAP path, do not proceed |
-| `output-path` parent does not exist | Create it, proceed |
-| Agent returns error / times out | Report the error to user. Suggest: check device connection (`hdc list targets`), verify HAP is valid, check `config.yaml` has real api_key |
-| `<output-path>/self-test-report.md` missing after agent completes | Report: "Agent completed but no report was generated. Check agent output at <output-path>." |
+| `test_case_path` does not exist | Ask user for correct path, do not proceed |
+| `hap_path` does not exist | Ask user for correct HAP path, do not proceed |
+| `output_path` parent does not exist | Create it, proceed |
+| Agent returns error / times out | Report the error to user. Suggest: check device connection (`hdc list targets`), verify HAP is valid, check the `autotest` block in `~/.hometrans/config.json` (or the `TEST_API_KEY` env var) has a real api_key |
+| `<output_path>/self-test-report.md` missing after agent completes | Report: "Agent completed but no report was generated. Check agent output at <output_path>." |
 | `self-test-report.md` exists but format is unrecognizable | Show the file path, report the first 80 lines as context, let user investigate |
 | Device not found (agent reports "No device") | Remind user: connect device via USB, verify `hdc list targets` shows the device |
 | Pre-case failures in report | Note: these are environment issues, not app defects. Highlight regular pass rate |
-| `<output-path>/testcases.json` or `app-metadata.json` missing after round 1 | Round 1 setup may have failed; inspect agent output at `<output-path>/` |
-| `<output-path>/testcases.json` is empty (`total == 0` in 2A) | Report: "testcases.json contains 0 cases — nothing to run." Exit loop with `stop_reason = no_testcases`. Do NOT enter the fix loop. |
+| `<output_path>/testcases.json` or `app-metadata.json` missing after round 1 | Round 1 setup may have failed; inspect agent output at `<output_path>/` |
+| `<output_path>/testcases.json` is empty (`total == 0` in 2A) | Report: "testcases.json contains 0 cases — nothing to run." Exit loop with `stop_reason = no_testcases`. Do NOT enter the fix loop. |
 | `self-tester` writes a sentinel FAIL report (first line `status: FAIL`) | Capture the `reason:` line. Exit loop with `stop_reason = agent_early_exit` and surface the captured reason. Do NOT enter the fix loop — these failures (config / device / autotest-dir / crash / timeout / setup=false preconditions) are not application defects. |
 | Fixer returns `confirmed == 0` (all false positives) | Exit loop with `stop_reason = no_confirmed_defects`. Surface the fix report summary. |
 | Build-fixer produces no signed HAP in ROUND_DIR | Report: "Build did not produce a signed HAP — cannot re-test." Exit loop with `stop_reason = no_signed_hap`. |
@@ -351,7 +362,7 @@ If failures remain (for `max_rounds_reached`), list them briefly (scenario names
 - **Fix-and-retest loop is opt-in**: Follow Step 2 Entry — ask the user unless they already opted in with "自动修复".
 - **Test → Fix → Build is the mandatory order**: Never re-test without rebuilding after a fix (would test old code). Never skip the build step in the loop.
 - **`CURRENT_HAP` must track the latest build**: After each 2C rebuild, update `CURRENT_HAP` to the new signed HAP from `ROUND_DIR`. Never re-test with the old HAP.
-- **Per-round snapshots**: Each round writes its latest artifacts to `<output-path>/` (root), then the SKILL snapshots per-round outputs to `<output-path>/round-{N}/`. The persistent JSONs (`testcases.json`, `app-metadata.json`) are written exactly once by round 1 and consumed unchanged by rounds 2+.
+- **Per-round snapshots**: Each round writes its latest artifacts to `<output_path>/` (root), then the SKILL snapshots per-round outputs to `<output_path>/round-{N}/`. The persistent JSONs (`testcases.json`, `app-metadata.json`) are written exactly once by round 1 and consumed unchanged by rounds 2+.
 - **Loop stop conditions**: Normal exits (3) — `all_passed`, `no_confirmed_defects`, `max_rounds_reached`. Error exits (3) — `no_signed_hap` (build did not produce HAP), `no_testcases` (empty testcases.json), `agent_early_exit` (self-tester sentinel FAIL: config / device / autotest-dir / crash / timeout / `setup: false` precondition failure).
 - **Loop iterations are strictly sequential**: Never launch more than one fixer or tester at a time.
 
@@ -363,7 +374,7 @@ If failures remain (for `max_rounds_reached`), list them briefly (scenario names
 - ❌ Reading the full `self-test-report.md` (read only first 80 lines for summary)
 - ❌ Reading the full `self-test-fix-report.md` (read only first 60 lines for summary)
 - ❌ Fabricating results when the report is missing or unreadable
-- ❌ Passing `output-path: <output-path>/round-N` to the agent — the agent always writes to `<output-path>/` root; per-round directories are populated by the SKILL's snapshot step
+- ❌ Passing `output_path: <output_path>/round-N` to the agent — the agent always writes to `<output_path>/` root; per-round directories are populated by the SKILL's snapshot step
 - ❌ Skipping the build step in the loop (rebuild is mandatory after each confirmed fix)
 - ❌ Re-testing with an old HAP after a build
 - ❌ Launching more than one fixer or tester at a time — loop rounds are strictly sequential

package/skills/hmos-resources-convert/SKILL.md

@@ -38,13 +38,13 @@ Try to build the Android project to produce an APK containing all merged resourc
 
 2. Run the build:
 ```bash
-cd <android_project>
+cd <android_project_dir>
 ./gradlew <variant>
 ```
 
-3. **If the build succeeds**: locate the APK in `<android_project>/app/build/outputs/apk/`. If multiple APKs exist, prefer the debug variant. Record `build_status = "success"` and proceed to Step 3 (decompile).
+3. **If the build succeeds**: locate the APK in `<android_project_dir>/app/build/outputs/apk/`. If multiple APKs exist, prefer the debug variant. Record `build_status = "success"` and proceed to Step 3 (decompile).
 
-4. **If the build fails**: record the build error output and `build_status = "failed"`. Also check if a previously-built APK already exists at `<android_project>/app/build/outputs/apk/`. If an existing APK is found, use it and record `build_status = "failed_using_cached_apk"`. If no APK exists at all, skip Step 3 entirely and proceed to Step 4 using the source `res/` directory. Set `resource_source = "source_res"`.
+4. **If the build fails**: record the build error output and `build_status = "failed"`. Also check if a previously-built APK already exists at `<android_project_dir>/app/build/outputs/apk/`. If an existing APK is found, use it and record `build_status = "failed_using_cached_apk"`. If no APK exists at all, skip Step 3 entirely and proceed to Step 4 using the source `res/` directory. Set `resource_source = "source_res"`.
 
 The reason we prefer the decompiled APK: it contains all merged resources from source code AND library dependencies (AARs, Maven artifacts). When falling back to source `res/`, library resources are missing, which means some resource references may be unresolvable. The conversion report will clearly flag this.
 
@@ -60,14 +60,14 @@ The skill bundles `apktool_3.0.1.jar` in its `tools/` directory. Java must be av
 
 The decompiled output at `<decompiled_output_path>/res/` contains the **complete merged resource set**. Set `resource_source = "decompiled_apk"` and use this as the conversion source.
 
-If no APK is available, skip this step. The conversion source will be the project's source `res/` directory (typically `<android_project>/app/src/main/res/`). Set `resource_source = "source_res"`.
+If no APK is available, skip this step. The conversion source will be the project's source `res/` directory (typically `<android_project_dir>/app/src/main/res/`). Set `resource_source = "source_res"`.
 
 ### Step 4: Convert Resources
 
 Read the detailed conversion rules from `references/conversion-rules.md` before performing conversions. Convert all resources found in the resource source directory (either decompiled `res/` or source `res/`). Read `references/resource-mapping-rules.md` before conversion as well — every conversion, skip, fallback, and unmappable case must also append structured mapping metadata for the final markdown written to `resource_mapping_path`.
 
 **Determining the source `res/` directory when using source fallback:**
-- Check `<android_project>/app/src/main/res/`
+- Check `<android_project_dir>/app/src/main/res/`
 - If multi-module, also check other module directories
 - If the project uses flavor source sets, include those too (e.g., `app/src/debug/res/`, `app/src/flavor/res/`)