feat: add self-check tip to check output (#2574)

* feat: add self-check tip to check output

* style: drop trailing period from self-check tip

Aligns the new tip with the other `Tip:` lines in `specify check`,
which don't end in a period. Per Copilot review feedback on #2574.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PascalThuet

docs/reference/core.md

@@ -69,6 +69,8 @@ specify check
 
 Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool.
 
+This command stays offline. If a command behaves like an older Spec Kit version or an expected CLI feature is missing, run `specify self check` to check whether your local CLI is behind the latest release.
+
 ## Version Information
 
 ```bash

docs/upgrade.md

@@ -388,6 +388,14 @@ Only Spec Kit infrastructure files:
 
 ### "CLI upgrade doesn't seem to work"
 
+If a command behaves like an older Spec Kit version, first check for local CLI drift:
+
+```bash
+specify self check
+```
+
+`specify check` is an offline environment scan; `specify self check` is the CLI version lookup.
+
 Verify the installation:
 
 ```bash

src/specify_cli/__init__.py

@@ -1200,6 +1200,8 @@ def check():
     if not any(agent_results.values()):
         console.print("[dim]Tip: Install a coding agent for the best experience[/dim]")
 
+    console.print("[dim]Tip: Run 'specify self check' to verify you have the latest CLI version[/dim]")
+
 
 def _feature_capabilities() -> dict[str, bool]:
     """Return stable local CLI capability flags for humans and agents."""

tests/test_check_tool.py

@@ -7,7 +7,13 @@
 
 from unittest.mock import patch, MagicMock
 
-from specify_cli import check_tool
+from typer.testing import CliRunner
+
+from specify_cli import app, check_tool
+from tests.conftest import strip_ansi
+
+
+runner = CliRunner()
 
 
 class TestCheckToolClaude:
@@ -103,4 +109,32 @@ def fake_which(name):
             return "/usr/bin/kiro" if name == "kiro" else None
 
         with patch("shutil.which", side_effect=fake_which):
-            assert check_tool("kiro-cli") is True
+            assert check_tool("kiro-cli") is True
+
+
+class TestCheckTip:
+    """`specify check` should point users to the existing version check."""
+
+    def test_check_shows_self_check_tip(self):
+        with patch("specify_cli.check_tool", return_value=True):
+            result = runner.invoke(app, ["check"])
+
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert (
+            "Tip: Run 'specify self check' to verify you have the latest CLI version"
+            in output
+        )
+
+    def test_check_tip_does_not_fetch_latest_release(self):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch(
+                "specify_cli._version._fetch_latest_release_tag",
+                side_effect=AssertionError("latest release lookup should not run"),
+            ) as fetch_latest,
+        ):
+            result = runner.invoke(app, ["check"])
+
+        assert result.exit_code == 0
+        fetch_latest.assert_not_called()