Test: link-steps workflow

.claude/commands/link-steps.md

@@ -21,13 +21,32 @@ the step's GitHub source via `scripts/link_steps.py`.
 2. Run the script (it fetches the latest Bitrise steplib spec from S3 and
    modifies files in place).
 
-3. If any files were changed, commit them:
+3. After the script runs, scan the same target files for **unresolved Step
+   references** — bold text (`**...**`) followed by "Step" or "Steps" that
+   the script left unlinked. These are cases where the doc uses a shortened
+   or informal name that doesn't exactly match the spec title.
+
+   For each unresolved reference:
+   a. Fetch the steplib spec (`https://bitrise-steplib-collection.s3.amazonaws.com/spec.json`)
+      and find the closest matching step title using substring or fuzzy matching.
+      For example, "Activate SSH key" is a shorthand for "Activate SSH key
+      (RSA private key)".
+   b. If a confident match is found, update the file to use the full spec title
+      in the link text and link it to the step's `source_code_url`.
+   c. If no confident match exists, report the unresolved reference to the user
+      and ask for guidance rather than guessing.
+
+4. If any files were changed, commit them:
    ```
    git add docs/
    git commit -m "Link Bitrise Step names to GitHub source"
    ```
 
-4. Report how many files were modified and which ones.
+5. Report:
+   - How many files were modified.
+   - Which Step names were auto-linked by the script.
+   - Which shortened names were resolved manually (and what full title was used).
+   - Any unresolved references that need human review.
 
 The script is idempotent: running it again on already-linked files makes no
 further changes.

docs/test-link-steps.mdx

@@ -0,0 +1,9 @@
+---
+title: Test link-steps workflow
+---
+
+This page is used to test the automatic Step name linking workflow.
+
+Use the **Activate SSH key** Step to authenticate with your repository over SSH.
+
+After cloning your code, you can cache dependencies with the **Save Gradle Cache** Step to speed up subsequent builds.

scripts/link_steps.py

@@ -19,6 +19,8 @@
   3. Single-word titles (e.g. "Script") are only linked when followed by "Step".
 """
 
+from __future__ import annotations
+
 import json
 import re
 import subprocess