diff --git a/README.md b/README.md
index 0aa77a1..976c9f0 100644
--- a/README.md
+++ b/README.md
@@ -59,8 +59,8 @@ steps:
 | `plugins` | Newline- or comma-separated plugin refs to install, as the registry names them (`bowrain`, `okapi-bridge`; a `kapi-` prefix is stripped). Pass `''` to install nothing | `bowrain` | No |
 | `auth-token` | Bowrain server JWT, exported as `BOWRAIN_AUTH_TOKEN` | — | No |
 | `server` | Bowrain server URL, exported as `BOWRAIN_SERVER_URL` | — | No |
-| `cache-tm` | Restore/persist the project translation memory across runs via the job cache (out of git). Runs only when a `*.kapi` recipe is present. Set `false` to disable | `true` | No |
-| `project-dir` | Directory holding the `.kapi` project for the TM cache | `.` | No |
+| `cache-tm` | Restore/persist the project translation memory across runs via the job cache (out of git). Runs only when a `kapi.yaml` recipe (or legacy `*.kapi`) is present. Set `false` to disable | `true` | No |
+| `project-dir` | Directory holding the `kapi.yaml` project for the TM cache | `.` | No |
 
 ## Outputs
 
@@ -102,7 +102,7 @@ image.
 4. **Add to PATH** — makes `kapi` available to all subsequent steps.
 5. **Configure auth** (optional) — exports `BOWRAIN_AUTH_TOKEN`/`BOWRAIN_SERVER_URL` when `auth-token` is set.
 6. **Install plugins** — installs each ref in `plugins` (default: `bowrain`) via `kapi plugins install`, cached keyed on the plugin set + OS + arch. Refs use the registry names; a `kapi-` binary prefix is stripped (`kapi-bowrain` → `bowrain`).
-7. **Restore project TM cache** (when a `*.kapi` recipe is present) — restores the latest translation memory for the branch from the job cache and, via a run-unique key, saves the grown TM back at job end. The TM is **derived state kept out of git**: it accumulates leverage across runs without being committed, and a cold cache simply rebuilds from the committed translations. No commits, no locking (per-branch, last-write-wins). Disable with `cache-tm: false`.
+7. **Restore project TM cache** (when a `kapi.yaml` recipe (or legacy `*.kapi`) is present) — restores the latest translation memory for the branch from the job cache and, via a run-unique key, saves the grown TM back at job end. The TM is **derived state kept out of git**: it accumulates leverage across runs without being committed, and a cold cache simply rebuilds from the committed translations. No commits, no locking (per-branch, last-write-wins). Disable with `cache-tm: false`.
 
 ## Caching
 
diff --git a/action.yml b/action.yml
index bb9b5c6..87a38b3 100644
--- a/action.yml
+++ b/action.yml
@@ -37,11 +37,11 @@ inputs:
       branch TM is restored at setup, and the grown TM is saved back at job end
       under a run-unique key, so leverage compounds without committing anything.
       A cold cache is fine — kapi rebuilds the TM from the committed translations.
-      Runs only when a *.kapi recipe is present. Set 'false' to disable.
+      Runs only when a kapi.yaml recipe (or legacy *.kapi) is present. Set 'false' to disable.
     required: false
     default: "true"
   project-dir:
-    description: "Directory holding the .kapi project (recipe + state) for the TM cache. Default: repository root."
+    description: "Directory holding the kapi.yaml project (recipe + state) for the TM cache. Default: repository root."
     required: false
     default: "."
 
@@ -180,7 +180,7 @@ runs:
           kapi plugins install "${plugin}"
         done <<< "${PLUGINS}"
 
-    # 11. Detect a kapi project — a committed *.kapi recipe. The TM cache only
+    # 11. Detect a kapi project — a committed kapi.yaml recipe (or legacy *.kapi). The TM cache only
     #     runs where there is a project TM to persist (the .kapi/ state dir is
     #     gitignored, so it may not exist yet; the recipe is the committed signal).
     - name: Detect kapi project
@@ -190,10 +190,10 @@ runs:
       env:
         PROJECT_DIR: ${{ inputs.project-dir }}
       run: |
-        if ls "${PROJECT_DIR}"/*.kapi >/dev/null 2>&1; then
+        if ls "${PROJECT_DIR}"/kapi.yaml >/dev/null 2>&1 || ls "${PROJECT_DIR}"/*.kapi >/dev/null 2>&1; then
           echo "found=true" >> "$GITHUB_OUTPUT"
         else
-          echo "found=false (no *.kapi recipe in ${PROJECT_DIR}); skipping TM cache" >&2
+          echo "found=false (no kapi.yaml recipe (or legacy *.kapi) in ${PROJECT_DIR}); skipping TM cache" >&2
           echo "found=false" >> "$GITHUB_OUTPUT"
         fi